Explore OAuth Machine to Machine Flows

This guide aims to explain the user about OAuth's Machine to Machine flows and its usage in CyberArk Identity sample app.

OAuth Machine to Machine (M2M)

In this automation era, we often come across scenarios where we require a secure authorized communication among multiple systems.
With the increase in automated devices, the scope for M2M communication has reached multiple parts such as communication between two backend devices, service to service communication, backend to demon, CLI client to internal service etc. In contrast with usual authentication where user uses Password or other MFAs to clear authentication, an application or a process needs to be authenticated by establishing trust in the system.

For these backend services to communicate securely and effectively, CyberArk Identity facilitates following two grant flows for secured machine to machine (M2M) communication.
• Client Credentials
• Resource Owner

Client Credentials flow

This grant type is for apps that can request an access token and access resources on its own. These apps often use services that call APIs without users. In this flow, client possess Client ID and Client Secret, with this information it requests an access token for protected resources. For more information see the: Client Credentials Flow RFC.

Following section provides more details about Client Credentials flow in Angular Java Sample App

  1. Following steps require OAuth client application to be created in the tenant, if not please create using OAuth App setup in the tenant.
  2. Please be ensured that OAuth Client details are updated in Settings page.
  3. Select Scenario 1 from demo app and clear authentication. Please refer clear authentication process for clearing authentication.
  4. After successful authentication of the user, user is redirected to Login Protocols page. Select Machine To Machine card as highlighted below.
932932
  1. From the drop down, select Client Creds and hit Build Token URL.
851851

📘

Note

  1. This Build Token URL triggers an API which uses data provided in Settings page.

  2. A preview of Token Endpoint and payload information is displayed for the user which can be used as a reference pattern for incorporating M2M flow in your personalized custom apps.

10631063
  1. Upon clicking submit, tokenset and claims data can be obtained.
460460 454454

📘

Note:

  1. CyberArk Identity maintains Authorization server and Resource Server as a single server.
  2. Using the access_token obtained from above step, we can invoke API Endpoints or resources.
  1. By clicking on Try Another Flow, a logout API call is triggered to logout the current user. It redirects to home page.

Resource Owner flow

In this flow, the client application provides its own user interface in which the user enters their credentials and grants access to resources. This information is then sent to the CyberArk Identity server which returns an access token to the client. Since this flow does not involve redirection to a CyberArk Identity to obtain authorization, it should only be used in highly privileged client applications such as native applications running on an OS. For more information see the Resource Owner Flow RFC.

Following section provides more details about Resource Owner flow in Angular Java Sample App

  1. Create and configure the app as mentioned in OAuth App setup in the tenant.
  2. Please be ensured that OAuth Client details are updated in Settings page.
  3. Select Scenario 1 from demo app and clear authentication. Please refer clear authentication process for clearing authentication.
  4. After successful authentication of the user, user is redirected to Login Protocols page. Select Machine To Machine card as highlighted below.
932932
  1. From the drop down, select Resource Owner and hit Build Token URL.
859859

📘

Note:

  1. This Build Token URL triggers an API which uses data provided in Settings page.

  2. A preview of Token Endpoint and payload information is displayed for the user which can be used as a reference pattern for incorporating M2M flow in your personalized custom apps.

852852
  1. Upon clicking submit, tokenset and claims data can be obtained.
453453 460460

📘

Note:

  1. CyberArk Identity maintains Authorization server and Resource Server as a single server.
  2. Using the access_token obtained from above step, we can invoke API Endpoints or resources.
  1. By clicking on Try Another Flow, a logout API call is triggered to logout the current user. It redirects to home page.

APIs for M2M flow

  • api/tokenRequestPreview: Collects the payload from data provided in Settings page. The result of this API contains Token Endpoint along with its payload which you can use while integrating this feature in your personalized apps.
POST https://identitydemo.acmeinc.com:8080/api/tokenRequestPreview

For Client Credential flow:
{
  "authFlow": "OAUTH",
  "grantType": "client_credentials"
}

For Resource Owner flow:

{
  "authFlow": "OAUTH",
  "grantType": "password",
  "userName": "[email protected]",
  "password": "Temp5678"
}
{
  "Success": true,
  "Result": {
    "apiEndPoint": "https://aamXXXX.my.idaptive.qa/OAuth2/Token/oauthclient",
    "payload": {
      "grantType": "client_credentials",
      "clientId": "[email protected]",
      "clientSecret": "Temp1234",
      "scope": "all"
    }
  },
  "ErrorMessage": null
}
  • api/tokenSet: Based on the grant type provided in payload, this API calls either requestTokenWithPassword or requestTokenWithClientCreds SDK method to get access token, token_type, scope, expires_in and refresh_token properties which can be used by the client to request for protected resource.
POST https://identitydemo.acmeinc.com:8080/api/tokenSet

For Client Credential flow:
{
  "authFlow": "OAUTH",
  "grantType": "client_credentials or password"
}

For Resource Owner flow:

{
  "authFlow": "OAUTH",
  "grantType": "password",
  "userName": "[email protected]",
  "password": "testTest1"
}
{
  "Success": true,
  "Result": {
    "access_token": "eyJ…aw",
    "token_type": "Bearer",
    "scope": "all",
    "expires_in": 7200
  },
  "ErrorMessage": null
}
  • api/claims: This API decodes the access token obtained in previous API to view user metadata.
GET https://identitydemo.acmeinc.com:8080/api/claims?token=<access_token>
{
  "Success": true,
  "Result": {
    "auth_time": 1635411780,
    "iss": "https://aamXXXX.my.idaptive.qa/",
    "iat": 1635412935,
    "aud": "2dfc9c9d-0411-4036-a47d-6180866a8fb6",
    "unique_name": "[email protected]",
    "exp": 1635420134,
    "sub": "a470a1a7-e059-416d-9467-070b97ca55bc",
    "scope": "all"
  },
  "ErrorMessage": null
}

📘

Note:

All APIs should contain XSRF-TOKEN set in cookie and request header.
Header: X-XSRF-TOKEN: xsrf token value
Cookie: XSRF-TOKEN: xsrf token value