CTMS - Authentication

Overview

The following steps show how to authenticate with user name and password via OAuth2's Resource Owner Password Credentials (ROPC) grant.

For additional information and other options, see Authentication. Other authorization options usually also have different ways to refresh or invalidate a token.

Authentication should always use the following steps:

  1. Acquire an access token

  2. Use the access token for calls to CloudUX.

  3. Refresh the token regularly.

  4. When the session is not needed anymore: log out and invalidate the access token.

Acquire an access token

Steps:

  1. Call GET on https://cloudux-host/auth where cloudux-host is the host name of your CloudUX installation. The result is a HAL resource with, among others, the link auth:identity-providers:

    {
  "_links": {
    "auth:identity-providers": [
      {
        "href": "https://cloudux-host/..."
      }
    ],
    ...
  }
}

  2. Call GET on the href of the auth:identity-providers link rel. The response contains a list of identity providers in the property _embedded. One of them has a link auth:ropc-default:

    {
  "_embedded": {
    "auth:identity-provider": [
      {
        "_links": {
          "auth:ropc-default": [
            {
              "href": "https://cloudux-host/..."
            }
          ]
        },
        "kind": "oauth"
      },
      ...
    ]
  }
}

  3. Send a POST request to the URL in the property href of that identity provider.

    • Use an x-www-form-urlencoded body with:

      • grant_type=password

      • username set to the user name of the caller

      • password set to the password of the caller

    • Set the HTTP header Authorization to Basic followed by the HTTP basic authentication token from your app record.

      POST /auth/sso/login/oauth2/ropc/ad HTTP/1.1
Host: cloudux-host
Content-Type: application/x-www-form-urlencoded
Authorization: Basic {HTTP basic token from app record}
Accept: application/json
Content-Length: **

grant_type=password&username=johndoe&password=1234

  4. The result contains the access token to use in the property access_token:

    {
    "access_token": "MzFlYjlhY2EtNDdiZC00MzhmLThiY2YtZGY5ODY2YmQ0ZGRk",
    "expires_in": 900,
    "token_type": "Bearer",
    ...
}

    The property expires_in contains the expiration time of the token in seconds.

Use the access token

There are two ways to use the access token for REST calls to CloudUX.

avidAccessToken cookie

The authentication call sets a cookie avidAccessToken with the access token as value. If your client implementation has proper cookie support, the calls to CloudUX will use that access token automatically.

Authorization header

You can set the Authorization header to Bearer followed by your access token to pass the access token to CloudUX:

Authorization: Bearer MzFlYjlhY2EtNDdiZC00MzhmLThiY2YtZGY5ODY2YmQ0ZGRk

Refresh the access token

Steps:

  1. The original GET request to https://cloudux-host/auth above also returns the link auth:token:

    {
  "_links": {
    "auth:token": [
      {
        "href": "https://cloudux-host/...",
        "name": "current"
      }
    ],
    ...
  }
}

  2. Take the auth:token link and call the URI in the href with a valid access token in the Authorization header or the avidAccessToken cookie. The result contains information about the token and the link auth-token:extend:

    {
  "_links": {
    "auth-token:extend": [
      {
        "href": "https://cloudux-host/..."
      }
    ],
    ...
  },
  ...
}

  3. Call the href of that link with HTTP method POST to extend the expiration time of the access token.

Log out

To log out and invalidate the access token:

  1. The original GET request to https://cloudux-host/auth above also returns the link auth:token:

    {
  "_links": {
    "auth:token": [
      {
        "href": "https://cloudux-host/...",
        "name": "current"
      }
    ],
    ...
  }
}

  2. Take the auth:token link and call the URI in the href with a valid access token in the Authorization header or the avidAccessToken cookie. The result contains information about the token and the link auth-token:extend:

    {
  "_links": {
    "auth-token:removal": [
      {
        "href": "https://cloudux-host/..."
      }
    ],
    ...
  },
  ...
}

  3. Call the href of that link with HTTP method DELETE to log out and invalidate the access token.

 

Previous page: Introducation and initial steps

Up: Quick start

Next page: Query the CTMS Registry