iOS and Android apps using AtHoc REST APIs
Before we begin today, look at my previous blog titled “New AtHoc v2 REST APIs” which explains how you can setup your AtHoc environment to use REST APIs in your application.
Once your environment is set up, you can start diving into the code. The first thing you’re going to need to do is authorize the user. This will allow you to use the ‘rest’ of the APIs to view devices, organizations, users, and of course, publish alerts.
There are three main types of authentication: password grant, authorization code grant, and implicit grant. This blog post will cover password grant and implicit grant. More information about the different types of authentication can be found in the “Authentication” section of the quick start guide located here. Once the user is authenticated and authorized, a bearer token is sent back which you pass into the headers of your future requests.
When should you use the different methods of authentication? For password grants, you need to program the client secret, the username, and password directly into the backend of the application. So, the question becomes, is the programmer trusted to keep that information safe? If so, then go right ahead. It also might be the only option in certain cases where there isn’t much of a front end. Realistically, this method should only be used if it is absolutely necessary
For implicit grant and code grant, the user is redirected to an authentication dialogue where they input their username and password. The user’s sensitive information is never actually dealt with in the code, so they don’t need to trust the programmer. This would be the preferred method in most cases.
Here is an example of how password grant authentication can be done in code.
The following code will also need to be added to properly format the URL:
As you can see, a simple POST request is made, sending all the relevant info. The client ID and client secret are from the API application you created on the AtHoc management system. The username and password are your username and password for the AtHoc management system. For the acr_values, you will put in tenant<your_organization_name>.
Another way to get authenticated is through an Implicit Grant. This method uses OAuth 2.0 and will redirect to an authentication dialogue in a browser and ask the user to sign in. Once the user has signed in, the token is sent back as a parameter in the redirect URI which links back to the app.
The first step to making an implicit grant is directing the user to the authentication dialogue in the browser.
Simply build the URL with the correct parameters (client id, scope, acr values, response type, and redirect URI). Add this to the intent filter and start the intent and that’s it! But the question is, how do you properly configure your redirect URI so that once you log in, you’re taken back to your app?
In your AndroidManifest.xml, add the following under the activity tag:
For iOS, you can follow these steps to configure the redirect URI:
1. Click on the project file to the left
2. Click on the "Info" tab.
3. Go all the way down and expand the "URL Types"
4. Add your URL scheme
Note: The scheme can really be whatever you want. You can also add a host if you want, but it is not necessary.
Now, your redirect URI is simply <scheme>://<host>. If you did not specify a host, leave it blank. It must match what was put in the API application when you setup your environment.
Now, for the app to be able to handle the redirect and extract the token from the URI, you can do the following:
I wrote a quick function to parse the URI but it only works in this specific case. You can parse the URI as needed to extract the access token.
With both the password grant and the implicit grant, the token is sent in a JSON blurb which is then parsed and stored in a global variable so it can be used in future requests. Now we can use this to send an alert!
Again, we make a simple POST request. The commonName parameter is the common name of the alert template that you’re using. This can be found on the AtHoc management system. This time, we’re sending in JSON in the request body, so we’ll use a JsonObjectRequest. We also need to send in the bearer token we retrieved earlier in order to publish the request.
Note: You only need the TemplateCommonName parameter to publish an alert, but you can add/modify the alert title, alert body, severity, and a lot more by adding some more information in the JSON request body. The details of what you can send and how to send it, along with all the different API calls you can make with AtHoc v2, can be found at https://<server>/api/v2/docs
And that’s it! Once you’ve done this, you should receive a text on your phone, or an email, or however you set up the alert template.