API and Mobile Configuration (Mobile Apps + API)

In this section we will see how we can implement an API for our scenario.

For simplicity, we will keep our implementation solely focused on authentication and authorization. As you will see in the samples, the input timesheet entry will be hard-coded, and the API will not persist the timesheet entry. Instead, it will simply echo back some of the info.

Define the API endpoints

First we need to define the endpoints of our API.

What is an API endpoint?

An API endpoint is a unique URL that represents an object. To interact with this object, you need to point your application to its URL. For example, if you had an API that could return either orders or customers, you might configure two endpoints: /orders and /customers. Your application would interact with these endpoints using different HTTP methods; for example, POST /orders could create a new order or GET /orders could retrieve the dataset of one or more orders.

For this implementation we will only define two endpoints; one for retrieving a list of all timesheets for an employee, and another which will allow an employee to create a new timesheet entry.

An HTTP GET request to the /timesheets endpoint will allow a user to retrieve their timesheets, and an HTTP POST request to the /timesheets endpoint will allow a user to add a new timesheet.

See the implementation in Node.js

Secure the Endpoints

When an API receives a request with a bearer Access Token as part of the header, the first thing to do is to validate the token. This consists of a series of steps, and if any of these fails then the request must be rejected with a Missing or invalid token error message to the calling app.

The validations that the API should perform are:

• Check that the JWT is well formed
• Check the signature
• Validate the standard claims

JWT.io provides a list of libraries that can do most of the work for you: parse the JWT, verify the signature and the claims.

Part of the validation process is to also check the Client permissions (scopes), but we will address this separately in the next paragraph of this document.

For more information on validating Access Tokens, see Validate Access Tokens.

See the implementation in Node.js

Check the Client’s Permissions

By now we have verified that the JWT is valid. The last step is to verify that the client has the permissions required to access the protected resources.

To do so, the API needs to check the scopes of the decoded JWT. This claim is part of the payload and it is a space-separated list of strings.

See the implementation in Node.js

Determine user identity

For both endpoints (retrieving the list of timesheets, and adding a new timesheet) we will need to determine the identity of the user.

For retrieving the list of timesheets this is to ensure that we only return the timesheets belonging to the user making the request, and for adding a new timesheet this is to ensure that the timesheet is associated with the user making the request.

One of the standard JWT claims is the sub claim which identifies the principal that is the subject to the claim. In the case of the Implicit Grant flow this claim will contain the user’s identity, which will be the unique identifier for the Auth0 user. You can use this to associate any information in external systems with a particular user.

You can also use a custom claim to add another attribute of the user - such as their email address - to the Access Token and use that to uniquely identify the user.

See the implementation in Node.js

Implement the Mobile App

In this section we will see how we can implement a mobile application for our scenario.

See the implementation in Android.

Authorize the User

To authorize the user we will implement the Authorization Code Flow with Proof Key for Code Exchange (PKCE). The mobile application should first send the user to the authorization URL along with the code_challenge and the method used to generate it:

https://{yourDomain}/authorize?
    audience=API_AUDIENCE&
    scope=SCOPE&
    response_type=code&
    client_id=YOUR_CLIENT_ID&
    code_challenge=CODE_CHALLENGE&
    code_challenge_method=S256&
    redirect_uri=https://YOUR_APP/callback

The GET request to the authorization URL should include the following values:

Parameter	Description
client_id	The value of your Auth0 Client Id. You can retrieve it from the Settings of your Application at the Auth0 Dashboard.
audience	The value of your API Identifier. You can retrieve it from the Settings of your API at the Auth0 Dashboard.
scope	The scopes which determine the claims to be returned in the ID Token and Access Token. For example, a scope of openid will return an ID Token in the response. In our example mobile app, we use the following scopes: create:timesheets read:timesheets openid profile email offline_access. These scopes allow the mobile app to call the API, obtain a Refresh Token, and return the user’s name, picture, and email claims in the ID Token.
response_type	Indicates the Authentication Flow to use. For a mobile application using PKCE, this should be set to code.
code_challenge	The generated code challenge from the code verifier. You can find instructions on generating a code challenge here.
code_challenge_method	Method used to generate the challenge. Auth0 supports only S256.
redirect_uri	The URL which Auth0 will redirect the browser to after authorization has been granted by the user. The Authorization Code will be available in the code URL parameter. This URL must be specified as a valid callback URL under your Application’s Settings.

See the implementation in Android.

Get the Credentials

After a successful request to the authorization URL, you should receive the following response:

HTTP/1.1 302 Found
Location: https://{yourDomain}/callback?code=AUTHORIZATION_CODE

Next you can exchange the authorization_code from the response for an Access Token that can be used to call your API. Perform a POST request to the Token URL including the following data:

curl.sh

curl --request POST \
  --url 'https://{yourDomain}/oauth/token' \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data grant_type=authorization_code \
  --data 'client_id={yourClientId}' \
  --data code_verified=YOUR_GENERATED_CODE_VERIFIER \
  --data code=YOUR_AUTHORIZATION_CODE \
  --data 'redirect_uri=https://{https://yourApp/callback}'

Parameter	Description
grant_type	This must be set to authorization_code.
client_id	The value of your Auth0 Client Id. You can retrieve it from the Settings of your Application at the Auth0 Dashboard.
code_verifier	Cryptographically random key that was used to generate the code_challenge passed to authorization URL (/authorize).
code	The authorization_code received from the previous authorize call.
redirect_uri	The URL must match the redirect_uri passed in the previous section to /authorize.

The response from the Token URL will contain:

{
  "access_token": "eyJz93a...k4laUWw",
  "refresh_token": "GEbRxBN...edjnXbL",
  "id_token": "eyJ0XAi...4faeEoQ",
  "token_type": "Bearer",
  "expires_in":86400
}

• access_token: An Access Token for the API, specified by the audience.
• refresh_token: A Refresh Token will only be present if you included the offline_access scope AND enabled Allow Offline Access for your API in the Dashboard.
• id_token: An ID Token JWT containing user profile information.
• token_type: A string containing the type of token, this will always be a Bearer token.
• expires_in: The amount of seconds until the Access Token expires.

You will need to store the above credentials in local storage for use in calling your API and retrieving the user profile.

See the implementation in Android.

Get the User Profile

To retrieve the User Profile, your mobile application can decode the ID Token using one of the JWT libraries. This is done by verifying the signature and verifying the claims of the token. After validating the ID Token, you can access its payload containing the user information:

{
  "email_verified": false,
  "email": "[e-mail]",
  "clientID": "q2hnj2iu...",
  "updated_at": "2016-12-05T15:15:40.545Z",
  "name": "[e-mail]",
  "picture": "https://s.gravatar.com/avatar/dummy.png",
  "user_id": "auth0|58454...",
  "nickname": "test.account",
  "created_at": "2016-12-05T11:16:59.640Z",
  "sub": "auth0|58454..."
}

See the implementation in Android.

Display UI Elements Conditionally Based on Scope

Based on the scope of the user, you may want to show or hide certain UI elements. To determine the scope issued to a user, you will need to inspect the scope which was granted when the user was authenticated. This will be a string containing all the scopes, so you therefore need to inspect this string to see whether it contains the required scope and based on that make a decision whether to display a particular UI element.

See the implementation in Android

Call the API

To access secured resources from your API, the authenticated user’s Access Token needs to be included in requests that are sent to it. This is accomplished by sending the Access Token in an Authorization header using the Bearer scheme.

See the implementation in Android.

Renew the Token

Refresh Tokens must be stored securely by an application since they do not expire and allow a user to remain authenticated essentially forever. If Refresh Tokens are compromised or you no longer need them, you can revoke the Refresh Tokens using the Authentication API.

To refresh your Access Token, perform a POST request to the /oauth/token endpoint using the Refresh Token from your authorization result.

A Refresh Token will only be present if you included the offline_access scope in the previous authorization request and enabled Allow Offline Access for your API in the Dashboard.

Your request should include:

curl.sh

curl --request POST \
  --url 'https://{yourDomain}/oauth/token' \
  --header 'content-type: application/x-www-form-urlencoded'

Parameter	Description
grant_type	This must be set to refresh_token.
client_id	The value of your Auth0 Client Id. You can retrieve it from the Settings of your Application at the Auth0 Dashboard.
refresh_token	the Refresh Token to use, from the previous authentication result.

The response will include the new Access Token:

{
  "access_token": "eyJz93a...k4laUWw",
  "refresh_token": "GEbRxBN...edjnXbL",
  "id_token": "eyJ0XAi...4faeEoQ",
  "token_type": "Bearer",
  "expires_in":86400
}

See the implementation in Android.