Enterprise Service Cloud - Docs

Access and Identity

Overview

The area Access and Identity deals with two topics. The first topic is how external identity providers are used for user logon at the Enterprise Service Cloud (ESC) and how user authorizations within the ESC can be controlled by their local ad group memberships. The second topic is how to access the ESC APIs which are protected by OAuth 2.0.

Description

Login and authorization

The Enterprise Service Cloud follows the own identity approach.

To do this, customers must provide an identity provider that authenticates their users and provides information about them via federation protocols (SAML 2.0 or OpenID Connect) to the ESC. Currently, the following attributes of a user are required:

  • Unique UserID
  • First name
  • Last name
  • E-Mail address
  • AD groups (which are relevant for ESC)

The AD groups can be assigned to permissions and business groups in the ESC. Users receive these permissions and business groups automatically when logging in based on their AD group memberships. This means that customers can control the authorizations and business groups of their users in the ESC locally via AD group memberships.

The onboarding of an identity provider is part of the ESC customer-onboarding process.

Access ESC APIs

The APIs of the ESC are protected against unauthorized access by OAuth 2.0open in new window. Therefore, all API requests must have a valid access token, which can be requested via the OAuth authorization code flow (see image below).

In order to request an access token, an OAuth client is first required. This can be ordered from Swisscom if it is not yet available. An OAuth client normally contains a client_id, client_secret as well as a redirect_url, which are needed in the following steps. The redirect_url is needed if a redirect to your application is necessary after requesting the authorization code. If not, http://localhost can be used.

The authorization code flow requires that the access token is requested by the same (service) user, who will also create API calls later on. To request an access token using the OAuth Authorization code flow the following steps must be performed:

Step 1: Request OAuth authorization code

The first step is to request an authorization code for a (service) user via a web browser by opening the following URL: https://[DOMAIN]/SAAS/t/[TENANT_NAME]/auth/oauth2/authorize?redirect_uri=[REDIRECT_URL]&client_id=[SERVICE_NAME]&response_type=code.

The browser will redirect you to your identity provider. After a successful authenication with the (service) user, you should be redirected to [REDIRECT_URL]/?code=ekTL9BnekWC5fIIXKnbapE73y07t3QxD&userstore=Userstore_881ca8b9-8331-4a43-92dd-5e7eb0a58d42.

Copy the code parameter (e.g. ekTL9BnekWC5fIIXKnbapE73y07t3QxD) from the URL in the address bar of your browser for the next step.

Step 2: Request OAuth access token and optional refresh token

You can use the authorization code, which is valid only once, to request an access token and optionally a refresh token (depends on the OAuth client) by performing an API call. You have to set the base64 encoded credentials of your OAuth client (client_id and client_secret) as Basic-Authorization-Header. The authorization code must be sent in the body of the API call.

Request

curl -X POST \
  https://[DOMAIN]/SAAS/t/[TENANT_NAME]/auth/oauthtoken \
  -H 'authorization: Basic [base64encode([SERVICE_NAME]:[SERVICE_PASSWORD])]' \
  -H 'cache-control: no-cache' \
  -H 'content-type: application/x-www-form-urlencoded' \
  -d 'grant_type=authorization_code&code=ekTL9BnekWC5fIIXKnbapE73y07t3QxD&redirect_uri=[REDIRECT_URL]'

Response

{
  "access_token": "[ACCESS_TOKEN]",
  "token_type": "Bearer",
  "expires_in": 604799,
  "refresh_token": "[REFRESH_TOKEN]",
  "scope": "user"
}

The access token can be used directly to access the ESC APIs and the refresh token to request new access tokens.

Step 3: Requesting ESC API

With the access token you can send requests to the ESC APIs. The access token must be set as Bearer-Authorization-Header within the request.

curl -X POST \
  https://[DOMAIN]/SAAS/t/[TENANT_NAME]/API/[API_ENDPOINT] \
  -H 'authorization: Bearer [ACCESS_TOKEN] \
  -H 'cache-control: no-cache' \

Step 4: Request new OAuth access token with refresh token (optional)

An application can use the refresh token to request new access tokens (e.g. if the old one is expired and the ESC API returns 401 Unauthorized) directly. The (service) user (e.g. via his browser) is not involved in that process. The token endpoint returns a new access token and a refresh token. So an update of the refresh token with the returned refresh token is necessary.

Request

curl -X POST \
  https://[DOMAIN]/SAAS/t/[TENANT_NAME]/auth/oauthtoken \
  -H 'authorization: Basic [base64encode([SERVICE_NAME]:[SERVICE_PASSWORD])]' \
  -H 'cache-control: no-cache' \
  -H 'content-type: application/x-www-form-urlencoded' \
  -d 'grant_type=refresh_token&refresh_token=sdbLgGDiIZ4NjtBilqJcU8iMNjAC9PkD&redirect_uri=[REDIRECT_URL]'

Response

{
  "access_token": "[ACCESS_TOKEN]",
  "token_type": "Bearer",
  "expires_in": 604799,
  "refresh_token": "[REFRESH_TOKEN]",
  "scope": "user"
}
Last Updated: