Tokens

Access tokens

Access tokens represent authorization and enable communication with backend resources that are protected by authorization filters that are set by App ID. The token conforms to JavaScript Object Signing and Encryption (JOSE) specifications. The token is formatted as JSON Web Tokens are signed with a JSON Web Key that uses the RS256 algorithm.

Example token:

Header:
{
   "alg": "RS256",
   "typ": "JWT",
   "kid": "appId-39a37f57-a227-4bfe-a044-93b6e6050a61-2018-08-02T11:57:43.401",
   "ver": 4
}
Payload:
{
   "iss": "https://us-south.appid.cloud.ibm.com/oauth/v4/39a37f57-a227-4bfe-a044-93b6e6050a61",
   "exp": 1551903163,
   "aud": [
   "968c2306-9aef-4109-bc06-4f5ed6axi24a"
   ],
   "sub": "2b96cc04-eca5-4122-a8de-6e07d14c13a5",
   "email_verified": true,
   "amr": [
   "cloud_directory"
   ],
   "iat": 1551899553,
   "tenant": "39a37f57-a227-4bfe-a044-93b6e6050a61",
   "scope": "openid appid_default appid_readprofile appid_readuserattr appid_writeuserattr appid_authenticated"
}

Identity tokens

Identity tokens represent authentication and contain information about the user. It can give you information about their name, email, gender, and location. A token can also return a URL to an image of the user. The token is formatted as JSON Web Tokens are signed with a JSON Web Key that uses the RS256 algorithm.

Example token:

Header:
{
   "alg": "RS256",
   "typ": "JWT",
   "kid": "appId-39a37f57-a227-4bfe-a044-93b6e6050a61-2018-08-02T11:57:43.401",
   "ver": 4
}
Payload:
{
   "iss": "https://us-south.appid.cloud.ibm.com/oauth/v4/39a37f57-a227-4bfe-a044-93b6e6050a61",
   "aud": [
   "968c2306-9aef-4109-bc06-4f5ed6axi24a"
   ],
   "exp": 1551903163,
   "tenant": "39a37f57-a227-4bfe-a044-93b6e6050a61",
   "iat": 1551899553,
   "email": "appid155@mailinator.com",
   "name": "appid155@mailinator.com",
   "sub": "2b96cc04-eca5-4122-a8de-6e07d14c13a5",
   "email_verified": true,
   "identities": [
   {
      "provider": "cloud_directory",
      "id": "118c0278-3526-4954-876b-cf70eb88efa2"
   }
   ],
   "amr": [
   "cloud_directory"
   ]
}

Identity tokens contain only partial user information. To see all the information that is provided by the identity provider, you can use the /userinfo endpoint.

Refresh tokens

App ID supports the ability to acquire new access and identity tokens without reauthentication, as defined in OIDC. A refresh token can be used to renew the access token so a user doesn't have to take any action to sign in, such as providing credentials. Similar to access tokens, refresh tokens contain data that allow App ID to determine whether you authorized. However, these tokens are opaque.

Refresh tokens are configured to have a longer life span than a regular access token. When an access token expires, the refresh token is still valid and can be used to renew the access token. App ID’s refresh tokens can be configured to last 1 - 90 days. To take full advantage of refresh tokens, persist the tokens for their full life span, or until they are renewed. A user cannot directly access resources with just a refresh token, which makes them much safer to persist than an access token. As best practice, refresh tokens should be securely stored by the client that received them and sent only to the authorization server that issued them.

For added convenience, App ID also renews its refresh token — and its expiration date — when the access token is renewed, allowing the user to remain logged in while they are active at some point before the current refresh token expires. Alternatively, if you would like to use refresh tokens yet force the user to log in periodically, your app might use only the refresh tokens that are returned when the user logs in by entering their credentials. However, we recommend always using the latest refresh token that is received from App ID, as described by the OAuth 2.0 specifications.

Although these tokens can streamline the login process, your app must not depend on them. They can be revoked at any time, such as when you believe that your refresh tokens were compromised. You can use two methods of revoking a refresh token, if needed. If you have the refresh token, you can revoke it based on RFC7009. Alternatively, if you have the user ID, you can revoke the refresh token by using the Management API. For more information about accessing the management API, see managing service access.

For examples of working with refresh tokens and how to use them to implement a remember-me functionality, check out the getting started samples.

Where do the tokens come from?

Tokens are issued through the App ID OAuth Server and are formatted as JSON Web Tokens (JWT). The tokens were signed with a JSON Web Key (JWK) with the RS256 algorithm.

What happens to the information that the token contains?

The access token contains a set of standard JWT claims and a set of App ID specific claims such as a tenant ID. The identity token contains user-specific information. The information in the tokens is stored as claims as part of a user's profile.

How are tokens received?

The tokens are received by your app after a successful authentication. Your app can use the tokens to retrieve information about user authorization and authentication. The access token can be used to gain access to protected resources by sending a request to the resource. To extract the tokens, your app must parse the header.

Example request:

GET /resource HTTP/1.1
Host: server.example.com
Authorization: Bearer  mF_9.B5f-4.1JqM mF_9.B5f-4.1JqM

How are tokens configured?

You can customize tokens by using custom claims mapping. For more information, see Customizing tokens.