Skip to content

Integrating Client Credentials app with OAuth2

Fanny Strudel edited this page Nov 2, 2016 · 1 revision

Getting Client Credentials access to VMware Identity Manager

This guide will walk you through getting OAuth 2.0 Access Tokens for your client credentials app. This guide is light weight to get you started quickly. If you want a deeper understanding of OAuth, please review the official spec at https://tools.ietf.org/html/rfc6749.

This flow is used for service to service communication, when the application is not acting on behalf of a user and needs to call VMware Identity Manager APIs.

Authentication Flow Overview

In OAuth Client Credentials authentication, your app sends VMware Identity Manager its Client Credentials and Client Secret. Identity Manager responds with an Access Token. Your app can use that Access Token to access Identity Manager APIs. The flow follows these steps:

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

  2. Your app sends its Client ID and Client Secret to Identity Manager.

  3. Identity Manager returns an Access Token to your app.

  4. When your Access Token expires, your app sends a new request to Identity Manager.

Setting up OAuth 2.0

Getting started

To get started with Identity Manager and OAuth, 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: One time only

The first step to getting OAuth tokens is registering your app. Registering your app’s details lets Identity Manager know your app should be considered a trusted client for the OAuth service.

You have to register a Client ID, Client Secret, and redirect URI with Identity Manager.

  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

  1. Click Create Client.

    Create Client

You should now see the Create Client dialog box. This dialog box allows you to enter your app’s Client ID and Shared Secret.

  1. Access Type: Set it to Service Client Token. This indicates that your app will access APIs on its own behalf, not on behalf of a user.

  2. Client ID: Enter the client identifier your app will use to authenticate itself to Identity Manager. Your Client ID must not match any Client 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: Acme_AppID

  3. Shared Secret: Click Advanced to generate the secret your app will use to authenticate with Identity Manager. We recommend clicking Generate Secret to have Identity Manager create a secure secret for your app; if you create your own secret, ensure it is difficult for attackers to guess.

    Example: lxpdL1tW0LufQJP7eW1HHSA4Y5ZiEwt8ItvebMWXmYigDIrh

Click Add to register your app once you’ve entered your Client ID, Redirect URI, and Shared Secret. You’re now ready to begin using your app with Identity Manager’s Client Credentials flow.

Created OAuth2.0 Client

Getting Your Client Credentials Access Token

Token Request

When your app needs an Access Token to get access to Identity Manager APIs, it should make a request to the Identity Manager token endpoint:

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

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

The URL requires the following parameters in the body of the request, using the application/x-www-form-urlencoded format:

  • grant_type=client_credentials. Required.

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 ( : ). Using the Client ID and Secret from the App Registration section, the string would be:

Acme_AppID:lxpdL1tW0LufQJP7eW1HHSA4Y5ZiEwt8ItvebMWXmYigDIrh

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

  • Content-Type: application/x-www-form-urlencoded

Example request:

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

Body:

grant_type=client_credentials

Headers:

Authorization: Basic QWNtZV9BcHBJRDpseHBkTDF0VzBMdWZRSlA3ZVcxSEhTQTRZNVppRXd0OEl0dmViTVdYbVlpZ0RJcmg=
Content-Type: application/x-www-form-urlencoded

Token Response

Identity Manager checks your app’s Client ID and Secret and returns an Access Token. Your app can use the Access Token to make API calls to Identity Manager.

Identity Manager token response is 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 your application.

  • 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 do the Getting Your Client Credentials Access Token step again.

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

Example JSON response:

{
  "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJqdGkiOiJmN2E3ZTg4Mi0xNGI0LTRiZTItODA4Yi05MzliMWQ3ODhlZjciLCJwcm4iOiJBY21lX0FwcElEQFNJTEVSQiIsImRvbWFpbiI6IkxvY2FsIFVzZXJzIiwidXNlcl9pZCI6IjEwODc1ODIiLCJhdXRoX3RpbWUiOjE0Nzc5MzMwMDYsImlzcyI6Imh0dHBzOi8vc2lsZXJiLnZtd2FyZWlkZW50aXR5LmNvbS9TQUFTL2F1dGgiLCJhdWQiOiJodHRwczovL3NpbGVyYi52bXdhcmVpZGVudGl0eS5jb20vU0FBUy9hdXRoL29hdXRodG9rZW4iLCJjdHgiOiJbe1wibXRkXCI6XCJ1cm46b2FzaXM6bmFtZXM6dGM6U0FNTDoyLjA6YWM6Y2xhc3NlczpQYXNzd29yZFByb3RlY3RlZFRyYW5zcG9ydFwiLFwiaWF0XCI6MTQ3NzkzMzAwNixcImlkXCI6MjE3NzI5fV0iLCJzY3AiOiJhZG1pbiIsImlkcCI6IjAiLCJlbWwiOiJPQXV0aENsaWVudF9BY21lX0FwcElEQG5vcmVwbHkuY29tIiwiY2lkIjoiQWNtZV9BcHBJRCIsImRpZCI6IiIsIndpZCI6IiIsImV4cCI6MTQ3Nzk1NDYwNiwiaWF0IjoxNDc3OTMzMDA2LCJzdWIiOiIxZDIzY2IyYS0yMGYzLTRlNWUtYjdlZS03MWVhYmRiMmZhMmMiLCJwcm5fdHlwZSI6IlNFUlZJQ0UifQ.hk5VqIvTdGoj2gzZUmxN5lhoowwqSlBFVDKiK2JlhVOcrvR1LMsWZHaWyOavA6ubSWTobksL_MclMZA5ZvrboUfNNPTunvAmdRE3MM7xjyf1XvdSSEyfUcX31AGhnEgKyRnYXCeQ8_xUnMFP2aKT7wagJZevzJSz5zab6AHu27I",
  "token_type": "Bearer",
  "expires_in": 21599,
  "refresh_token": "rPUgvovP9RhWhZUlCwt0SQvqaDzIDQxN",
  "scope": "admin"
}

Refreshing your Access Token

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

The application needs to send the following request:

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

The URL requires the following parameters in the body of the request, using the application/x-www-form-urlencoded format:

  • grant_type=refresh_token. Required.

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

  • scope. Optional. The list of scopes separated by space and URL encoded.

This request also requires the following header:

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 ( : ). Using the Client ID and Secret from the App Registration section, the string would be:

Acme_AppID:lxpdL1tW0LufQJP7eW1HHSA4Y5ZiEwt8ItvebMWXmYigDIrh

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

  • Content-Type: application/x-www-form-urlencoded

Example request:

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

Body:

refresh_token=XzaJ6apKDevNV0ONpqlUE0WuaF9kfO8r&grant_type=refresh_token

Headers:

Authorization: Basic QWNtZV9BcHBJRDpseHBkTDF0VzBMdWZRSlA3ZVcxSEhTQTRZNVppRXd0OEl0dmViTVdYbVlpZ0RJcmg=
Content-Type: application/x-www-form-urlencoded

Identity Manager will respond with a new Access Token.

Example response:

{
 "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJqdGkiOiIxM2NjOTUyMi0zZWQwLTRkNjEtYTgyMi04MTdmYWVjYzAxNWMiLCJwcm4iOiJBY21lX0FwcElEQFNJTEVSQiIsImRvbWFpbiI6IkxvY2FsIFVzZXJzIiwidXNlcl9pZCI6IjEwODc1ODIiLCJhdXRoX3RpbWUiOjE0NzgwMjI0NDAsImlzcyI6Imh0dHBzOi8vc2lsZXJiLnZtd2FyZWlkZW50aXR5LmNvbS9TQUFTL2F1dGgiLCJhdWQiOiJodHRwczovL3NpbGVyYi52bXdhcmVpZGVudGl0eS5jb20vU0FBUy9hdXRoL29hdXRodG9rZW4iLCJjdHgiOiJbe1wibXRkXCI6XCJ1cm46b2FzaXM6bmFtZXM6dGM6U0FNTDoyLjA6YWM6Y2xhc3NlczpQYXNzd29yZFByb3RlY3RlZFRyYW5zcG9ydFwiLFwiaWF0XCI6MTQ3ODAyMjQ0MCxcImlkXCI6MjE3NzI5fV0iLCJzY3AiOiJhZG1pbiIsImlkcCI6IjAiLCJlbWwiOiJPQXV0aENsaWVudF9BY21lX0FwcElEQG5vcmVwbHkuY29tIiwiY2lkIjoiQWNtZV9BcHBJRCIsImRpZCI6IiIsIndpZCI6IiIsImV4cCI6MTQ3ODA0NDA0MCwiaWF0IjoxNDc4MDIyNDQwLCJzdWIiOiIxZDIzY2IyYS0yMGYzLTRlNWUtYjdlZS03MWVhYmRiMmZhMmMiLCJwcm5fdHlwZSI6IlNFUlZJQ0UifQ.BKMCTTK5kzN2pm0BwVbQob6AXXBBFOzptWQSKOtkQM7weSJNiblEoGgXosYr_DG-EGomSWvoICjdaH6eqJtvE9XZ9lq9M2XUP5D7VwAgRh00m5X7c0IcmuZB0MJDyvwaF0OvYiHGgsSqTlzzgrgIGqw6b8RQUtFjpEMkl95J0r8",
 "token_type": "Bearer",
 "expires_in": 21599,
 "refresh_token": "8RTPp9DNpOriJQcLa1LnYcoqEySV0WK9",
 "scope": "admin"
}

Refreshing your Refresh Token

If the Refresh Token expires, your app needs to use its Client ID and Client Secret to get a new one as described in Getting Your Client Credentials Access Token.

Validating your Access Token

Your app can validate a token by sending it to the Identity Manager token endpoint. If the token is valid, Identity Manager responds with “true”. Otherwise, Identity Manager responds with “false”.

Your app needs to send the following request:

GET https://[tenant location]/SAAS/API/1.0/REST/auth/token

The URL requires the following query parameters:

  • attribute=isValid. Required.

The URL requires the following headers:

Example Request:

GET https://acmecorp.vmwareidentity.com/SAAS/API/1.0/REST/auth/token?attribute=isValid

Headers:

Authorization: HZN
eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJqdGkiOiIxM2NjOTUyMi0zZWQwLTRkNjEtYTgyMi04MTdmYWVjYzAxNWMiLCJwcm4iOiJBY21lX0FwcElEQFNJTEVSQiIsImRvbWFpbiI6IkxvY2FsIFVzZXJzIiwidXNlcl9pZCI6IjEwODc1ODIiLCJhdXRoX3RpbWUiOjE0NzgwMjI0NDAsImlzcyI6Imh0dHBzOi8vc2lsZXJiLnZtd2FyZWlkZW50aXR5LmNvbS9TQUFTL2F1dGgiLCJhdWQiOiJodHRwczovL3NpbGVyYi52bXdhcmVpZGVudGl0eS5jb20vU0FBUy9hdXRoL29hdXRodG9rZW4iLCJjdHgiOiJbe1wibXRkXCI6XCJ1cm46b2FzaXM6bmFtZXM6dGM6U0FNTDoyLjA6YWM6Y2xhc3NlczpQYXNzd29yZFByb3RlY3RlZFRyYW5zcG9ydFwiLFwiaWF0XCI6MTQ3ODAyMjQ0MCxcImlkXCI6MjE3NzI5fV0iLCJzY3AiOiJhZG1pbiIsImlkcCI6IjAiLCJlbWwiOiJPQXV0aENsaWVudF9BY21lX0FwcElEQG5vcmVwbHkuY29tIiwiY2lkIjoiQWNtZV9BcHBJRCIsImRpZCI6IiIsIndpZCI6IiIsImV4cCI6MTQ3ODA0NDA0MCwiaWF0IjoxNDc4MDIyNDQwLCJzdWIiOiIxZDIzY2IyYS0yMGYzLTRlNWUtYjdlZS03MWVhYmRiMmZhMmMiLCJwcm5fdHlwZSI6IlNFUlZJQ0UifQ.BKMCTTK5kzN2pm0BwVbQob6AXXBBFOzptWQSKOtkQM7weSJNiblEoGgXosYr_DG-EGomSWvoICjdaH6eqJtvE9XZ9lq9M2XUP5D7VwAgRh00m5X7c0IcmuZB0MJDyvwaF0OvYiHGgsSqTlzzgrgIGqw6b8RQUtFjpEMkl95J0r8

If the token is valid, Identity Manager responds with true. Otherwise, Identity Manager responds with false.