Skip to content

Single sign on for Mobile

Fanny Strudel edited this page Oct 24, 2016 · 2 revisions

Single Sign-on for Mobile with VMware Identity Manager

Dynamic client registration

This guide will walk you through using Identity Manager to enable single sign-on for your mobile app using OpenID Connect. This guide is lightweight to get you started quickly. If you want a deeper understanding of OpenID Connect, please review the official spec at http://openid.net/specs/openid-connect-core-1_0.html.

This guide uses VMware’s Dynamic Client Registration flow, a special API based on OpenID Connect that assigns a Client ID and Client Secret to each instance of your mobile app.

A demo application is available at: https://github.com/vmware/idm/tree/master/samples/DynamicRegistrationAppAuthDemo-Android

Note: The Dynamic Client Registration flow is an adaptation of the OAuth 2.0 Authorization Code Grant for extra security on mobile devices. Unlike the standard Authorization Code Grant, the Dynamic Client Registration flow assigns a Client Secret and Client ID to each instance of a mobile app. Each Client Secret is associated with a user. These extra security features mean that if an attacker compromises an instance of your mobile app and discovers the app's Client Secret, the attacker is unable to use that Secret to access APIs on behalf of other users. In addition, these dynamic client secrets can be revoked on a per-user basis, allowing you to deny access to compromised apps without denying access to every instance of your app.

Table of Contents

Authentication Flow Overview

In OpenID Connect authentication, Identity Manager performs authentication of your users and passes your app an ID Token that contains information about the user and the authentication. The special Dynamic Client registration flow adds security to standard OpenID Connect flows by assigning each instance of your app an individual Client ID and Client Secret.

The Dynamic Client registration flow follows these steps:

  1. You register your app as an OpenID Connect client in Identity Manager. You must only complete this step once for your app.

  2. The user tries to access your app.

  3. The app checks for a Client ID and Client Secret.

  4. If your app doesn't already have a Client ID and Client Secret, your app sends the user to Identity Manager.

  5. Identity Manager authenticates the user according to the policies you set up.

  6. Identity Manager returns the user, an Authorization Code, and an Activation Code to your app.

  7. Your app sends the Activation Code to Identity Manager over TLS.

  8. Identity Manager returns a Client ID and Client Secret.

  9. Your app sends the Authorization Code to Identity Manager over TLS. This call requires the Client ID and Secret from the last step.

  10. Identity Manager returns an ID Token, Authorization Token, and Refresh Token to your app.

  11. When the user's ID Token expires, your app uses the Refresh Token to request a new ID Token over TLS.

  12. When the Refresh Token expires, your app begins the flow again at step 3.

This flow is illustrated in the sequence diagram below:

Dynamic Client Registration OAuth2.0 flow

Setting up OpenID Connect in Identity Manager

Getting Identity Manager Access

To get started with Identity Manager and OpenID Connect, you must have an Identity Manager tenant and a user with admin rights. If you don’t already have a tenant, you can get a free trial tenant at http://www.air-watch.com/lp/vmware-identity-manager-free-trial/ to test your app integration.

App Registration

Registering your app’s details lets Identity Manager know your app should be considered a trusted client for the OpenID Connect grants.

For mobile apps, you have to register your app’s Template ID and redirect URI with Identity Manager. You also have to choose what information your app requests from Identity Manager and the end user.

  1. To register your app, log in to the Identity Manager Admin Console as your tenant admin.

  2. Click the Catalog triangle dropdown.

  3. Click Settings.

    Settings

  4. Click Remote App Access.

    Remote App Access

  5. Click the Templates tab.

  6. Click Create Template.

    Create Template

You should now see the Create Template dialog box. This dialog box allows you to enter your app’s Template ID and Redirect URI. It also lets you choose what Scopes (information types) your app requests from Identity Manager and the user during End User Authentication.

  • Template ID: Enter an ID for your mobile app. Each instance of your mobile app will use this Template ID to request an instance-specific Client ID and Secret from Identity Manager. Your Template ID must not match any Template ID already being used by your tenant. You can use the following characters: alphanumeric (A-Z, a-z, 0-9) period (.), underscore (_), and hyphen (-) and at sign (@).

    Example: AcmeCorp_TemplateID

  • Redirect URI: Enter the redirection endpoint Identity Manager will use to respond to your app’s requests. For mobile apps, you should use a custom scheme that your app will register with the mobile OS. Your custom scheme should include proprietary and unusual words such as your company's name to reduce the chance of accidental collisions between custom schemes registered on a user's device. A good practice is to reverse your corporate domain name and use that as at least part of your custom scheme (for example, AcmeCorp.com could become com.Acmecorp.mobileapp3). Your URI can include query parameters, but it should not include any URI fragments.

Security tip: Make sure that your app’s redirection endpoint cannot be used as an open redirector. The easiest way to do this is by not allowing redirects away from the endpoint you register with Identity Manager. If you must redirect users or responses away from your endpoint, make sure you only redirect them to known, whitelisted URIs. Failing to validate redirect URIs lets attackers steal tokens or codes by redirecting them away from your app.

Example: com.AcmeCorp://oauth2redirect

  • Scopes: Choose what kinds of information Identity Manager sends your app by default.

Security tip: Only select the scopes your app needs. End users may feel nervous about granting your app permission to see too much of their information; limiting your scopes also reduces the amount of user information transferred over the network.

The following Scopes are available:

  • OpenID: Always select this scope; it lets Identity Manager know that it should send your app an ID Token after end-user authentication.

  • User: Always select this scope; it lets Identity Manager know your application needs access to user information.

  • Email: Select this scope if you need information about user email. The email attribute gives the user’s email, and the email_verified attribute tells your app whether the user’s email has been verified as belonging to the user.

  • Profile: Select this scope if you need the user’s name information. The family_name attribute gives you the user’s last name and the given_name attribute gives you his or her first name.

The following scopes are not used at this time:

  • Application: Not used at this time.

  • NAPPS: Not used at this time.

  • User Grant: Check this box if you want the users to see a consent screen before your app can access the resources on their behalf.

Click Add to register your app once you’ve entered your Template ID, Redirect URI, and Scopes. You’re now ready to begin using your app with Identity Manager.

App Template Creation

Once your template is defined, you cannot edit it.

Example of a defined template:

Registered App Template

2. User Authentication and App Activation

Once your app is registered with Identity Manager, it can ask Identity Manager to authenticate a user. Your app sends the user in a browser to the /register endpoint to be authenticated. If the “User Grant” box was checked during App Registration, Identity Manager also asks the user for consent for your app to access his or her information.

After authenticating the user, Identity Manager sends your app two codes. Your app exchanges Your app exchanges that code with Identity Manager for an Access Token, a Refresh Token (if Issue Refresh Token was selected), and an ID Token (if the OpenID scope was selected).

End User Authentication

When your app needs to authenticate a user, it should send the user to Identity Manager. Identity Manager handles the authentication in a “black box” process independent of your app, eliminating the need for your app to contain any authentication logic.

To authenticate your user, redirect his or her browser to the following URL:

[tenant_location]/SAAS/auth/device/register

where [tenant location] is the hostname of your tenant. Note that you must use HTTPS in all your calls to Identity Manager.

The URL requires the following query parameters:

  • response_type=code. Required.

  • device_name=[device's unique ID]. Required; this is a string that serves as a unique identifier for the device your app is installed on. This string should be the device serial number or another unique ID.

  • redirect_uri=[your redirect URI]. Required. [your redirect URI] must match the URI you entered in App Registration.

  • state=[your app state]. Required. This is a state token your app generates to ensure an attacker can’t send a fake response to your app (known as cross-site request forgery). The token should be around 30 characters long and generated using a random number generator.

  • scope=[your scopes]. Required. The scopes of information that should be returned to your app. This parameter must contain the OpenID scope. Your client can request fewer scopes than you initially selected in App Registration, but not more. For example, you could initially select the scopes openid, user, profile, and email, but only request the scopes openid, user, and profile in your request. Identity Manager would only ask the user for permission to share the scopes you requested, and it would only return the scopes you requested to your app in the ID Token.

  • user_device=[a JSON representation of the user’s device information]. Required. The JSON represents the user’s device and must be URL encoded. An example of a decoded version is:

{
 "osFamily":"Android",
 "extendedAttributeMap": {"model":"Android SDK built for x86"},
 "machineName":"unknown",
 "osVersion":24,
 "osName":"Android",
 "deviceId":"7ea00d46-35eb-4cd9-951a-4b790c14bb4f"
}
  • app_product_id=[Template ID]. Required. This is the name of the Template ID registered in Identity Manager during the App Registration.

Example URL (with line breaks for readability):

https://acmecorp.vmwareidentity.com/SAAS/auth/device/register?
scope=openid+profile+email+user
&device_name=unknown+Android+SDK+built+for+x86
&state=5aPY-C1JSeyTiUPWV_DLDw
&response_type=code
&app_product_id= AcmeCorp_TemplateID
&user_device=%7B%22osFamily%22%3A%22Android%22%2C%22extendedAttributeMap%22%3A%7B%22model%22%3A%22Android+SDK+built+for+x86%22%7D%2C%22machineName%22%3A%22unknown%22%2C%22osVersion%22%3A24%2C%22osName%22%3A%22Android%22%2C%22deviceId%22%3A%227ea00d46-35eb-4cd9-951a-4b790c14bb4f%22%7D
&redirect_uri=com.AcmeCorp%3A%2F%2Foauth2redirect
&type=register

Authentication Event

After your app sends your user’s browser to Identity Manager, Identity Manager authenticates the user. Identity Manager then sends the browser back to your app using the Redirect URI you entered in App Registration.

Authentication Response

Identity Manager’s responses comes to your app’s Redirect URI. Your app receives a short-lived Authorization Code it can exchange for an Access Token and ID Token, and an Activation Code it can exchange for a Client ID and Client Secret. Your app also receives a state token that is identical to the state token it passed Identity Manager.

Identity Manager’s response follows this pattern:

[redirect URI]?code=[authorization code]&activation_code=[activation code]&state=[your app’s state]

For example, if your app used the example URL above, Identity Manager would return the following (with line breaks for readability):

com.AcmeCorp://oauth2redirect?
code=gacOWXzL6Lwo4Ad
&activation_code=e2hsf98dg8s6es
&state=5aPY-C1JSeyTiUPWV_DLDw

The code parameter contains the Authorization Code your app must exchange for an Access Token in the Access Token Request step. The activation_code parameter contains a value your app must send in the App Activation Request step.

State Matching

Your app must match the state token it receives from Identity Manager with the one it sent in the Authentication Request. If the tokens do not match, an attacker may be impersonating Identity Manager.

App activation request

If your app doesn’t have a Client ID and Client Secret or if its Refresh Token has expired, it must send an activation request to Identity Manager. This activation request gives your app instance a unique Client ID and Client Secret. Your app then uses that ID and Secret to authenticate itself to Identity Manager in the Token Request.

Once an instance of your app has been activated, it does not need to make another activation request until its Refresh Token expires.

To activate an instance of your app, send a POST request to the following endpoint:

POST https://[tenant location]/SAAS/API/1.0/REST/oauth2/activate

The endpoint requires the following request body:

  • activation_code. This is same value as the activation code received as part of the response to the Authentication Response. This parameter is passed in the HTTP body; it's the only thing in the HTTP body.

An example of activation request:

POST https://acmecorp.vmwareidentity.com/SAAS/API/1.0/REST/oauth2/activate

Body: e2hsf98dg8s6es

App Activation Response

Identity Manager returns a client_id and client_secret to your application in exchange for the activation code. Your app must store these values to use in future Access Token Requests.

An example of activation response:

{
  "client_id": "AcmeCorp_TemplateID@e9d80cec-4e12-4970-828d-ae4557e33173",
  "client_secret":"KVk06Qre8WQLNpMJVcNHsX5d7vHCVFf0DkxR1sDcT90dCZv"
}

Access Token Request

The Authorization Code your app received in the Authentication Response is very short lived; your app needs to exchange it for a longer term Access Token, an ID Token, and a Refresh Token. To exchange the code for an Access Token, your app should send a POST request to the following URL:

POST https://[tenant location]/SAAS/auth/oauthtoken

The URL requires the following query parameters:

  • grant_type=authorization_code. Required.

  • code=[your authorization code]. Required. This parameter contains the Authorization Code Identity Manager sent to your app in Authentication Response.

  • redirect_uri=[your redirect URI]. Required. [your redirect URI] must match the URI you entered in App Registration.

The call also requires the following headers:

  • Authorization: Basic [base64Encode(clientId + ":" + secret)]. Required. Your app should use its Client ID and Client Secret to authenticate with Identity Manager using Basic Authentication. To create your Basic Credentials, create a string with your app’s Client ID and Client Secret, separated by a colon ( : ). If Identity Manager returned the following Client ID and Secret:

    client_id: AcmeCorp_TemplateID@e9d80cec-4e12-4970-828d-ae4557e33173 client_secret: KVk06Qre8WQLNpMJVcNHsX5d7vHCVFf0DkxR1sDcT90dCZv

    then the string would be:

    AcmeCorp_TemplateID@e9d80cec-4e12-4970-828d-ae4557e33173:KVk06Qre8WQLNpMJVcNHsX5d7vHCVFf0DkxR1sDcT90dCZv

    After the string is Base64 encoded, the Authorization Header is as follows:

    Authorization: Basic QWNtZUNvcnBfVGVtcGxhdGVJREBlOWQ4MGNlYy00ZTEyLTQ5NzAtODI4ZC1hZTQ1NTdlMzMxNzM6S1ZrMDZRcmU4V1FMTnBNSlZjTkhzWDVkN3ZIQ1ZGZjBEa3hSMXNEY1Q5MGRDWnY=
    

Example request (with line breaks for readability):

POST https://acmecorp.vmwareidentity.com/SAAS/auth/oauthtoken?

grant_type=authorization_code
&code=gacOWXzL6Lwo4Ad
&redirect_uri=com.acmecorp%3A%2F%2Foauth2redirect

Headers:

Authorization: Basic
QWNtZUNvcnBfVGVtcGxhdGVJREBlOWQ4MGNlYy00ZTEyLTQ5NzAtODI4ZC1hZTQ1NTdlMzMxNzM6S1ZrMDZRcmU4V1FMTnBNSlZjTkhzWDVkN3ZIQ1ZGZjBEa3hSMXNEY1Q5MGRDWnY=

Token Response

Identity Manager validates your app’s Authorization Code and returns an ID Token and an Access Token. The ID Token describes the user (and the Authentication Event in which the user authenticated with Identity Manager). The Access Token gives your app permission to access APIs on behalf of a user; if you are only using Identity Manager to authenticate the user, your app can ignore this token.

Identity Manager will also send your app a Refresh Token. The Refresh Token can be used to renew your app’s permission to access APIs on behalf of the user when your Access Token expires.

Identity Manager’s responds with a JSON object with the following attributes:

  • access_token. This attribute contains an Access Token in JWT format. Your app can use this token to access Identity Manager APIs on behalf of the user.

  • token_type. This attribute tells your application what type of Access Token it was given. At this time, Identity Manager tokens are always bearer tokens.

  • expires_in. The Access Token will expire in the number of seconds given in this attribute. If the Access Token expires, your app will have to use the Refresh Token to request a new Access Token or begin the Authenticating Users flow again.

  • refresh_token. This attribute contains the Refresh Token your app can exchange for a new Access Token.

  • scope. This attribute lists the scopes of information that the ID Token contains.

  • id_token. This attribute contains an ID Token in JWT format. The ID Token describes the user and the Authentication Event in which the user authenticated with Identity Manager.

Example JSON response:

{
  "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJqdGkiOiI0YWY5OTljNC0zMTk3LTQ2MzgtYThhYy0xY2NlNDBlYjEyMmMiLCJwcm4iOiJsb2NhbF9hZG1pbkBTSUxFUkIiLCJkb21haW4iOiJMb2NhbCBVc2VycyIsInVzZXJfaWQiOiI3MDk3MjgiLCJhdXRoX3RpbWUiOjE0NzY4MjYwNTIsImlzcyI6Imh0dHBzOi8vc2lsZXJiLnZtd2FyZWlkZW50aXR5LmNvbS9TQUFTL2F1dGgiLCJhdWQiOiJodHRwczovL3NpbGVyYi52bXdhcmVpZGVudGl0eS5jb20vU0FBUy9hdXRoL29hdXRodG9rZW4iLCJjdHgiOiJbe1wibXRkXCI6XCJ1cm46b2FzaXM6bmFtZXM6dGM6U0FNTDoyLjA6YWM6Y2xhc3NlczpQYXNzd29yZFByb3RlY3RlZFRyYW5zcG9ydFwiLFwiaWF0XCI6MTQ3NjgyNjAzOSxcImlkXCI6MjE3NzI5fV0iLCJzY3AiOiJvcGVuaWQgcHJvZmlsZSB1c2VyIGVtYWlsIiwiaWRwIjoiMCIsImVtbCI6InNpbGVyYkB2bXdhcmUuY29tIiwiY2lkIjoiT2F1dGhVc2VyQWNjZXNzVG9rZW5UZXN0IiwiZGlkIjoiIiwid2lkIjoiIiwiZXhwIjoxNDc2ODQ3NjUyLCJpYXQiOjE0NzY4MjYwNTIsInN1YiI6IjVhOWNjYmMyLWUwYTEtNGMwYS1hNzFhLTAzN2Y4ZDNiNTI0ZiIsInBybl90eXBlIjoiVVNFUiJ9.gkOH03AzvnA3jWtXbAJyW7OzFntGmcOX_VuqwPLp6VYsnZG5_RY_pjF1uPPW9k2_k5hLr8ZhJcQxJGMNlKfgq0udQWcPKgz3OVvpUQv7BsByeLljQcn-jPfE6hEwjfWyLm88daH0ca7sjwdaaO-gsNaHJ4hkUi_8MgL7_PZ7EgM",
  "expires_at": 1475602412739,
  "id_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJlbWFpbCI6Impkb2VAYWNtZWNvcnAuY29tIiwidXBkYXRlZF9hdCI6MTQ3Mzg5ODQ4OSwiZXhwIjoxNDc0OTk3NzM0LCJpYXQiOjE0NzQ5OTc2MTQsInN1YiI6Impkb2VAYWNtZWNvcnAiLCJpc3MiOiJodHRwczovL2Rldi52bXdhcmVpZGVudGl0eS5hc2lhL1NBQVMvYXV0aCIsImF1ZCI6WyJBY21lQ29ycF9UZW1wbGF0ZUBlOWQ4MGNlYy00ZTEyLTQ5NzAtODI4ZC1hZTQ1NTdlMzMxNzMiXSwiYXV0aF90aW1lIjoxNDc0OTk3NjE0LCJhenAiOiJBY21lQ29ycF9UZW1wbGF0ZUBlOWQ4MGNlYy00ZTEyLTQ5NzAtODI4ZC1hZTQ1NTdlMzMxNzMiLCJhdF9oYXNoIjoiNVplTVlWSEh0WElwcmdSaHZJZFZWUSIsImdpdmVuX25hbWUiOiJKb2huIiwiZmFtaWx5X25hbWUiOiJEb2UiLCJlbWFpbF92ZXJpZmllZCI6dHJ1ZX0.qLszb-07xnhinT7oaklI2OQHFoEetLzlzlNTfeo1Y3GcwqUD-ZV6tXYC6AJoFx_RkHS5XYi67iwCawsz8RGx-ypMz2hPg1xTFbgUhecLNg6y7DqfEfEGHRf98H0ksEA--eA15e-3wuDTaB5skwc52OzNLxRijo8o0d-iDDUQuyQ",
  "refresh_token": "E2ADMN1btjcHilYpSTIh6Y6xp6wymp4r",
  "token_type": "Bearer"
}

Both the ID Token and Access Tokens are JWTs. Your app can decode them to see information about the user and authentication event. Your app should also verify the signatures of both tokens.

Using the ID Token

The ID Token is formatted using the JWT standard. You can decode the token using base64 decoding to reveal claims about the user and Authentication Event.

The payload of the ID Token contains claims about the user. Identity Manager ID Tokens can contain the following attributes:

  • email: Provided if the email scope was checked in App Registration. This attribute contains the user’s email address.

  • updatedAt: This attribute tells your application the last time the user’s account was updated in Identity Manager. Given in Unix time.

  • exp: The time at which the Access Token will expire. Given in Unix time.

  • iat: The time at which the ID Token was issued. Given in Unix time.

  • sub: The user’s unique identifier. Contains a user identifier and an Identity Manager tenant identifier, divided by an at sign ( @ ). For example, the unique identifier user@EXAMPLETENANT identifies a user known as “user” and an Identity Manager instance known as “EXAMPLETENANT”.

  • iss: The Identity Manager endpoint that issued the ID Token. Your app should verify that this matches the URL used in the Access Token Request.

  • aud: The audience the ID Token was issued for; your app must verify that the value in aud matches its Client ID.

  • auth_time: The time at which the ID token was issued. Given in Unix time.

  • azp: Authorized party - the party the token was given to. This value should match your app’s Client ID.

  • at_hash: The base64url encoding of the left-most half of the hash of the octets of the ASCII representation of the Access Token value. Identity Manager uses the RS256 hash algorithm. Your app must verify that the at_hash value matches the hashed value of the access token. To verify the match, hash the access_token value with SHA-256, then take the left-most 128 bits and base64url encode them. The at_hash value is a case sensitive string.

  • given_name: Provided if the profile scope was checked in App Registration. The user’s first name.

  • family_name: Provided if the profile scope was checked in App Registration. The user’s last name.

  • email_verified: Provided if the email scope was checked in App Registration. This value is true if someone has taken action to confirm the email address and if it is believed that the email belongs to the subject of the ID token.

Example ID Token payload:

{
  "at_hash": "5ZeMYVHHtXIprgRhvIdVVQ",
  "aud": [
    "AcmeCorp_TemplateID@e9d80cec-4e12-4970-828d-ae4557e33173"
  ],
  "auth_time": 1474997614,
  "azp": "AcmeCorp_TemplateID@e9d80cec-4e12-4970-828d-ae4557e33173",
  "email": "user2@acme.com",
  "email_verified": true,
  "exp": 1474997734,
  "family_name": "LastName2",
  "given_name": "User2",
  "iat": 1474997614,
  "iss": "https://acmecorp.vmwareidentity.com/SAAS/auth",
  "sub": "user2@acmecorp",
  "updated_at": 1473898489
}

3. Refreshing your Access Token

The Access and ID Tokens have limited lifetimes. Your app will get an error if it tries to access resources using an expired token. If your Tokens expire, your app should request a new Access and ID Tokens using the Refresh Token.

The application needs to send the following request:

POST https://[tenant location]/SAAS/auth/oauthtoken

The URL requires the following query parameters:

  • grant_type=refresh_token. Required.

  • client_id=[client_id]. Required. The client ID as retrieved during the Activation Request.

  • refresh_token=[refresh token]. Required. The Refresh Token sent back by Identity Manager during the first Access Token Request.

This request also requires the following header:

  • Authorization: Basic [base64Encode(clientId + ":" + secret)]. Required. Your app should use its Client ID and Client Secret to authenticate with Identity Manager using Basic Authentication. To create your Basic Credentials, create a string with your app’s Client ID and Client Secret, separated by a colon ( : ). If Identity Manager returned the following Client ID and Secret:

    client_id: AcmeCorp_TemplateID@e9d80cec-4e12-4970-828d-ae4557e33173 client_secret: KVk06Qre8WQLNpMJVcNHsX5d7vHCVFf0DkxR1sDcT90dCZv

    then the string would be:

    AcmeCorp_TemplateID@e9d80cec-4e12-4970-828d-ae4557e33173:KVk06Qre8WQLNpMJVcNHsX5d7vHCVFf0DkxR1sDcT90dCZv

    After the string is Base64 encoded, the Authorization Header is as follows:

    Authorization: Basic QWNtZUNvcnBfVGVtcGxhdGVJREBlOWQ4MGNlYy00ZTEyLTQ5NzAtODI4ZC1hZTQ1NTdlMzMxNzM6S1ZrMDZRcmU4V1FMTnBNSlZjTkhzWDVkN3ZIQ1ZGZjBEa3hSMXNEY1Q5MGRDWnY=
    

Example request (with line breaks for readability):

POST

refresh_token=XzaJ6apKDevNV0ONpqlUE0WuaF9kfO8r
&client_id=AcmeCorp_TemplateID%e9d80cec-4e12-4970-828d-ae4557e33173
&grant_type=refresh_token

Headers:

Authorization: Basic QWNtZUNvcnBfVGVtcGxhdGVJREBlOWQ4MGNlYy00ZTEyLTQ5NzAtODI4ZC1hZTQ1NTdlMzMxNzM6S1ZrMDZRcmU4V1FMTnBNSlZjTkhzWDVkN3ZIQ1ZGZjBEa3hSMXNEY1Q5MGRDWnY=

Identity Manager will respond with a new Access Token.

Example response:

{
  "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJqdGkiOiI0YWY5OTljNC0zMTk3LTQ2MzgtYThhYy0xY2NlNDBlYjEyMmMiLCJwcm4iOiJsb2NhbF9hZG1pbkBTSUxFUkIiLCJkb21haW4iOiJMb2NhbCBVc2VycyIsInVzZXJfaWQiOiI3MDk3MjgiLCJhdXRoX3RpbWUiOjE0NzY4MjYwNTIsImlzcyI6Imh0dHBzOi8vc2lsZXJiLnZtd2FyZWlkZW50aXR5LmNvbS9TQUFTL2F1dGgiLCJhdWQiOiJodHRwczovL3NpbGVyYi52bXdhcmVpZGVudGl0eS5jb20vU0FBUy9hdXRoL29hdXRodG9rZW4iLCJjdHgiOiJbe1wibXRkXCI6XCJ1cm46b2FzaXM6bmFtZXM6dGM6U0FNTDoyLjA6YWM6Y2xhc3NlczpQYXNzd29yZFByb3RlY3RlZFRyYW5zcG9ydFwiLFwiaWF0XCI6MTQ3NjgyNjAzOSxcImlkXCI6MjE3NzI5fV0iLCJzY3AiOiJvcGVuaWQgcHJvZmlsZSB1c2VyIGVtYWlsIiwiaWRwIjoiMCIsImVtbCI6InNpbGVyYkB2bXdhcmUuY29tIiwiY2lkIjoiT2F1dGhVc2VyQWNjZXNzVG9rZW5UZXN0IiwiZGlkIjoiIiwid2lkIjoiIiwiZXhwIjoxNDc2ODQ3NjUyLCJpYXQiOjE0NzY4MjYwNTIsInN1YiI6IjVhOWNjYmMyLWUwYTEtNGMwYS1hNzFhLTAzN2Y4ZDNiNTI0ZiIsInBybl90eXBlIjoiVVNFUiJ9.r_EI3gd8vrW5ULvzpJLL-TuKfqeJlSjUlY7V6kFvWQMRRZsEFJONMuhMcgrZ2K8KB3JOQgiexIHPhA4mzBDrAh_mwdPR5nzi6I7_PC-vawwjTyFw6JIouo0l-xg6ZDUca91MKx5UDTwNvswai__5791FReo_0tXE1FsdRwrmJJw",
  "expires_in": 604799,
  "refresh_token": "XzaJ6apKDevNV0ONpqlUE0WuaF9kfO8r",
  "scope": "openid profile user email",
  "token_type": "Bearer"
}

Refreshing your Refresh Token

If the Refresh Token expires, your app needs to go through the entire flow again, beginning with the call to the /register endpoint described in 2. User Authentication and App Activation.

Note: Your app must use the same device unique identifier (device_name) each time it makes a call to the /register endpoint. This prevents end users from seeing multiple versions of your app in their Identity Manager self-service portal.

Getting more information on a user

To get more information about a user than is contained in the ID token, your app should make a call to Identity Manager’s SCIM /Me endpoint.

Note: This endpoint is based on the SCIM standard for managing users in cloud applications; for more information on SCIM and the /Me endpoint, see the SCIM specification at https://tools.ietf.org/html/rfc7644.

List of additional information available from /Me

When your app calls the /Me endpoint, it gets the following information:

  • Username. The user’s username in Identity Manager.

  • User ID. This is the unique identifier assigned to the user in Identity Manager.

  • User metadata. Information about when the user was created, modified, and what instance of Identity Manager he or she belongs to.

  • User given name. The user’s given first and last names.

  • User email addresses.

  • The user’s groups in Identity Manager. These may be local to Identity Manager or imported from a user store, such as LDAP or Microsoft Active Directory.

  • The user’s roles in Identity Manager. These may be local to Identity Manager or imported from a user store, such as LDAP or Microsoft Active Directory.

Making the user information request

To get additional user information, your app should make the following request:

GET https://[tenant location]/SAAS/jersey/manager/api/scim/Me

This request requires the following header:

  • Authorization: Bearer [user’s Access Token]. Required. Your app must use the Access Token it received on behalf of the user who logged into Identity Manager in 2. User Authentication and App Activation. The Access Token authorizes your app to request information about a user. It also identifies which user’s information Identity Manager should return.

Example request:

GET https://acmecorp.vmwareidentity.com/SAAS/jersey/manager/api/scim/Me

Headers:

Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJqdGkiOiI0YWY5OTljNC0zMTk3LTQ2MzgtYThhYy0xY2NlNDBlYjEyMmMiLCJwcm4iOiJsb2NhbF9hZG1pbkBTSUxFUkIiLCJkb21haW4iOiJMb2NhbCBVc2VycyIsInVzZXJfaWQiOiI3MDk3MjgiLCJhdXRoX3RpbWUiOjE0NzY4MjYwNTIsImlzcyI6Imh0dHBzOi8vc2lsZXJiLnZtd2FyZWlkZW50aXR5LmNvbS9TQUFTL2F1dGgiLCJhdWQiOiJodHRwczovL3NpbGVyYi52bXdhcmVpZGVudGl0eS5jb20vU0FBUy9hdXRoL29hdXRodG9rZW4iLCJjdHgiOiJbe1wibXRkXCI6XCJ1cm46b2FzaXM6bmFtZXM6dGM6U0FNTDoyLjA6YWM6Y2xhc3NlczpQYXNzd29yZFByb3RlY3RlZFRyYW5zcG9ydFwiLFwiaWF0XCI6MTQ3NjgyNjAzOSxcImlkXCI6MjE3NzI5fV0iLCJzY3AiOiJvcGVuaWQgcHJvZmlsZSB1c2VyIGVtYWlsIiwiaWRwIjoiMCIsImVtbCI6InNpbGVyYkB2bXdhcmUuY29tIiwiY2lkIjoiT2F1dGhVc2VyQWNjZXNzVG9rZW5UZXN0IiwiZGlkIjoiIiwid2lkIjoiIiwiZXhwIjoxNDc2ODQ3NjUyLCJpYXQiOjE0NzY4MjYwNTIsInN1YiI6IjVhOWNjYmMyLWUwYTEtNGMwYS1hNzFhLTAzN2Y4ZDNiNTI0ZiIsInBybl90eXBlIjoiVVNFUiJ9.YTiJQWXY3soeZVc5BcJXqu1OWd1lvQre2g6eKp0Rd9O1s4t_hi1wXQt2h7MEG6BQssT47DkxFxX9G8LagUzBrnoYiqOFgnmfhRfqyCiv0xHb_qC5cjg66bSMBulTODgAZ8_CX4a2YACDfhTinl171Gy9rajxjH192O4Hq24FgUc

Identity Manager will respond with additional information about the user in JSON format.

Example response:

{
    "active": true,
    "emails": [
        {
            "value": "jdoe@acmecorp.com"
        }
    ],
    "groups": [
        {
            "display": "ALL USERS",
            "type": "DIRECT",
            "value": "07a7653a-ad24-428a-ad00-92672bacf0d2"
        }
    ],
    "id": "5a9ccbc2-e0a1-4c0a-a71a-037f8d3b524f",
    "meta": {
        "created": "2016-06-20T18:23:27.629Z",
        "lastModified": "2016-07-13T23:03:31.757Z",
        "location": "https://acmecorp.vmwareidentity.com/SAAS/jersey/manager/api/scim/Users/5a9ccbc2-e0a1-4c0a-a71a-037f8d3b524f",
        "version": "W/\"1468451011757\""
    },
    "name": {
        "familyName": "Doe",
        "givenName": "John"
    },
    "roles": [
        {
            "display": "User",
            "value": "6b0c926e-0d82-4272-9a47-b45535f0ca2d"
        },
        {
            "display": "Administrator",
            "value": "9d7162a5-8a8b-452f-8a68-c57ff872ee12"
        }
    ],
    "schemas": [
        "urn:scim:schemas:core:1.0",
        "urn:scim:schemas:extension:workspace:1.0",
        "urn:scim:schemas:extension:enterprise:1.0",
        "urn:scim:schemas:extension:workspace:mfa:1.0"
    ],
    "urn:scim:schemas:extension:workspace:1.0": {
        "domain": "Local Users",
        "internalUserType": "LOCAL",
        "userStatus": "1"
    },
    "userName": "jdoe"
}