Securing the REST API

Using Client-based Authentication with OAUTH2

Client IDs enable you to secure your REST API by providing unique keys that work in conjunction with a user's CSM privileges. REST API Users must provide a client ID and their CSM login credentials to work with the REST API.

You can create separate client IDs to control access for:

  • Specific Users
  • Specific Integration Tools

OAuth2 password flow with refresh tokens is currently supported. After a successful login, an Access token and a Refresh token are returned.

An Access token is needed for all subsequent calls to the REST API to identify you as a valid API user. This token is based on the client ID and your CSM credentials. The lifespan of the Access token is based on the client ID's settings. Access tokens tend to have a relatively short lifespan and can be refreshed with a Refresh token.

Refresh tokens are used to periodically refresh the Access token without the need to provide credentials again. Refresh tokens tend to have a longer lifespan than Access tokens and are also based on the client ID's settings. Once the Refresh token has expired or the user is logged out, a full login must be performed to obtain new tokens.

It is not always necessary to use Refresh tokens, which are generally considered safer over non-encrypted transport protocols, such as HTTP. If you use an HTTPS connection, you can increase the Access token lifespan and use Access tokens for all subsequent connections.

Note: To further secure your system, use SSL.

Users who log in to the REST API client consume a CSM license.

Authentication Modes

The REST API uses the authentication types specified for the CSM Browser Client:
  • Internal

    Uses the login ID and password specified for a user in CSM. If no other mode is specified, Internal mode is used.

  • Windows

    Uses the server variable LOGON_USER to attempt to find a CSM user. You can also use domain\username and password.

  • LDAP

    Uses the LDAP settings configured for CSM and the server variable LOGON_USER to attempt to find a CSM user. You can also use domain\username and password.

  • SAML

    Uses the SAML settings configured for CSM to validate credentials and find the CSM user.

    For SAML configuration steps, refer to Configuring the REST API for SAML Authentication.

Use the token operation to get an access token for a specific authentication type.

Obtaining API Client IDs

client IDs are created in the CSM Administrator Client:

  1. From the Main window, select Security.
  2. Click Edit REST API client settings.
  3. Click the Plus icon.
  4. Provide these settings for the client ID:
    Setting Description
    Name Provide a name for the client ID.
    Culture Select a language-specific culture.
    Token lifespan Set the amount of time the access token will be active.
    Refresh Token lifespan Set the amount of time the refresh token will be active.
    API access is enabled When selected, the client ID is enabled. When cleared, the client ID is disabled. Clear the check box to disable the client ID without deleting it.
    Allow anonymous access Select to make the REST API available to anonymous users.
  5. Copy the client ID and provide it to REST API users.
© Copyright 2016 Cherwell Software, LLC. All rights reserved.