Using service accounts

A Secure Web Sessions service account enables you to use the SWS API to authenticate to SWS and access data.

When you create a service account, a new public/private key pair is generated and downloaded to your machine. This is the only copy of the private key. You are responsible for storing the private key securely. Note its location and ensure the key is accessible to your application; it needs the key to make authenticated API calls.

Before you begin

You need to be a SWS Admin to create a service account.

Create a service account

In the Secure Web Sessions portal, go to Identities > Service accounts.
Click the Create service account button.

Set the following properties:

Property	Description
Name	The name of the service account. This name appears in the activities performed with this account.
Description	A description of the service account. This appears in the service accounts list.
Role	Choose a role for the service account that defines its permissions. Administrator - Can perform all actions and view all tenant information. Auditor - Can only perform GET actions on Activities. Viewer - Can perform GET actions on all tenant information, but not create/modify.
Status	The status of the new service account.
Confirmation	Select the check box to confirm that you want to create a service account.

Click Save to create the .json file that is required to make the API calls, and save it on your computer. The .json file contains the following:

Service Account ID
Private key
DiscoveryURL

The following example shows the contents of the .json file.

{
    "serviceAccountId": "11ea6140f94d5f82a3712de9ac6f6b24",
    "privateKey": "-----BEGIN RSA PRIVATE KEY-----MIIEowIBAAKCAQEAhmfhZYpMev5bfrFDCyJmvKIHPL/0OkDhTicXZHd37uhTK8MNzKdY2+ohApYbF/grS7U6+bLEBs2PoLd4Eqv/cj89CI5VCaZlf5jeHPM4mys39QpJ1ljo8PqJN/sn8ZUXG/CH6Nalx+3DRdYauXPLGOJ5p4w1HyGIPSLAzaUnrg8oE4xZmR1UVFDh8Zqv+ORVIlx4SdIxs8cLgKc2G2DYqQerig8a7fDrIsJeaRyjsFN451N45JVEpMEpkOCN7XDufgJrMSN1iPQXgi4ACLEpa1xVPdMYaTnrAJ3saU71i0afL+7i6x/lhF7GRAEskGG+LYQe8U+VBHHgtN7vLuHtvwIDAQABAoIBAAssze/MXOmJBoB1KpbdaF9ctW9Wom7JgDIoS+idikpB5NBpqlcOvvOh9tapNl1609a6ncmvFF9gbgW123Tp+hY8rc1tUCK6RAwk4KrViipUoJVuIo+A2vVWT1xpNHwAomg/Sn2Qgz4pRagj0hsDRqquAeFtZelNt28l2ZP/nFn7Z2bp7JK+XGbqd7j17CUCfbvXH7yQDTg34DjNRJ+U1DUToO5w9YPxuP5MjepDGsVKe64fEGFE9a8H4uGbSXBDHeNHRghOK+Htg3Rz6OrEd//2QBlv07p8wBiv4z+ZMBBpCkTXb5z+mXzXTKQv0fj6yfP3QlCjPQCHFbKNqsEFEikCgYEA2PgxkVeYoKPkxmihiRIV25XFJ94uKpdt9Jb5EwevQogGGMJMpysgy16fyPm5PpskHGCjHDEnr0OA6cA+Mo3d/fchLdDhYcTwNoLUrS9PG55xOC6RGGtYevQ+NOBWiEV4pkTB8TwuUI8jHzh+b1ZMkFkP5qx8x3GD9YCVNGyoVDUCgYEAnpV9eniJTJmAa54hpQyMqpT13CgvkmWiT/aHr77TGAk9zYDeyKkOYIFNX5p4EKOeqTfFzxWOPNIqsGfPvRF3HqTMmbaxmfxrvHKflwisw8j10oPqU1JIfJ5kUvj/9a18qcLVKXoIcGLNjZr4Iy9t4euDAXJefqgdH8sIgVzNEKMCgYAwFyL1chL0WB9XEs3rEcUifJnMcmSNMC9A7U2buDJSbs/bIQXYb6i/KuQDqcYzaDOizpCYqRSAtleWd/PRRLyVk/cYrpmmD/6mNm1pTXkdSAsURs4GOZTM++Hl2muTnMJXKBpMm+gwFunT+7OafehOfk8V89lcY366JZvsmMDemQKBgCjth+7dwQGl9EDSFPjV3lAAFdv1+yEbXeKpS6eN5kkjyXGKOvUqvG0nseJkqWwR7lbZ8BFcDNOhoibZBAJVyZp9Cdj6D6ggP2XpZ0rBkGUPLnJgXU+XwuF2t4m6fcTYO35MrFsCBb+LoGVVg4kBKqjN8YekDsM9fBbCfbV1T+9lAoGBAJ/xVihYF5JlQcQ2ISaLd8cHUXEH+WLklR0YyeV/EJB2TmoMji7+4oz2dILNwOXmcJZMPnrOPqGDyRv4UAIWrgRntfm4FsaV321PpE02yfujjXYUNGZcQRUJO5oex8sI8AJrPb4zQWYI6nxa6Y41l+cIJ7EFypEnndvsht/P6gRb-----END RSA PRIVATE KEY-----",
    "discoveryURI": "https://auth.alero.io/auth/realms/serviceaccounts/.well-known/openid-configuration"
}

Create a JSON Web Token (JWT)

After you create the .json file in the SWS portal, and you have the Service Account ID and private key, do the following:

Create a JSON Web Token (JWT). There are two ways to create a token; using the API token helper, or you can manually create the token.
Call APIs using the Access Token received from the Authorization Server.

SWS authenticates clients with a Private Key JWT Client Authentication method (private_key_jwt), which is defined in OpenID Connect 1.0 and the JWT Profile for OAuth 2.0 Client Authentication specifications. This is an authentication method that can be used by clients to authenticate to the authorization server when using the token endpoint. Only clients that have registered a public key in the SWS portal (by creating a service account) and have signed a JWT using a matching private key (in the file downloaded when creating a Service Account) can authenticate.

When SWS authenticates clients with Private Key JWT Client Authentication, the clients send a request that contains an assertion in JWT format to the token endpoint of the server. SWS validates the signature and the payload of the assertion.

Recommendation: Although your application can complete these tasks by interacting directly with OAuth 2.0 using HTTP, server-to-server authentication interactions require applications to create and cryptographically sign JSON Web Tokens (JWTs). It is highly recommended to avoid any impact on the security of your application by using using libraries that abstract the cryptography away from your application code.

Automatically create a token using the API Token Helper

The simplest way to create an access token is by using the public-api-token-helper file. This token creator helper file is available from the CyberArk Marketplace.

Make sure you have Java installed on your computer; either OpenJDK, Oracle or Zulu.

To create an access token:

Go to CyberArk Marketplace. Download the JAR file public-api-auth-helper-0.0.1-SNAPSHOT-application.jar.
Open a terminal or command prompt and run the following command with the replaced values.

java.exe -jar <path-to-public-api-auth-helper-0.0.1-SNAPSHOT-application.jar> -t <tenant ID> -p <path-to-secret-file>

The syntax includes the following details:
- The JAR file you downloaded from CyberArk Marketplace.
- -t <tenant ID> - Enter your tenant ID value.
- -p <path-to-secret-file> - Enter the service account secret file path that you received when you created your service account.
After you run the command, look at the output for the access token.
Copy and paste the token to the authorization header value in your request.

Manually create a token

After you create the .json file in the SWS portal, and you have the Service Account ID and private key, do the following:

Create a JSON Web Token (JWT), which includes a header, a claim set, and a signature.
Request an access token from the token endpoint of the SWS Authorization Server.
Handle the JSON response that the Authorization Server returns.

The following sections describe each stage.

Generating the signed JWT

A JWT is composed of three parts: a header, a claim set, and a signature. The header and claim set are JSON objects. These JSON objects are serialized to UTF-8 bytes, then encoded using the Base64url encoding. The header, claim set, and signature are concatenated together with a period (.) character.

A JWT is composed of the following parts:

{Base64url encoded header}.{Base64url encoded claim set}.{Base64url encoded signature}

Header

The header consists of two fields that indicate the signing algorithm and the format of the assertion. Both fields are mandatory, and each field has only one value. As additional algorithms and formats are introduced, this header will change accordingly.

Service accounts rely on the RSA SHA-256 algorithm and the JWT token format. As a result, the JSON representation of the header is as follows:

{"alg":"RS256","typ":"JWT"}

The Base64url representation of this is as follows:

eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9

Claim Set

The JWT claim set contains information about the JWT, including the issuer, the time the token was issued, and the lifetime of the token. Most of the fields are mandatory. Like the JWT header, the JWT claim set is a JSON object and is used to calculate the signature.

The JWT must contain the required claims in the following table.

Claim	Detail	Required
iss	Issuer. This must contain the client_id of the OAuth Client. "<TenantID>.<SerivceAccountID>.ExternalServiceAccount"	ü
sub	Subject. This must contain the client_id of the OAuth Client. "<TenantID>.<SerivceAccountID>.ExternalServiceAccount"	ü
aud	Audience. The aud (audience) claim. A value that identifies the Authorization Server as an intended audience. The Authorization Server must verify that it is an intended audience for the token. Specify the URL of the Authorization Server endpoint. US data center: https://auth.alero.io/auth/realms/serviceaccounts EU data center: https://auth.alero.eu/auth/realms/serviceaccounts Canada data center: https://auth.ca.alero.io/auth/realms/serviceaccounts Australia data center: https://auth.au.alero.io/auth/realms/serviceaccounts London data center: https://auth.uk.alero.io/auth/realms/serviceaccounts	ü
jti	JWT ID. A unique identifier for the token, which can be used to prevent reuse of the token. These tokens must only be used once.	ü
exp	Expiration time on or after which the JWT must not be accepted for processing.	ü
iat	Time when the JWT was issued.	û

The following example shows then JSON representation of the required fields in a JWT claim set:

{
  "aud": "https://auth.alero.io/auth/realms/serviceaccounts",
  "iss": "11ea48f8dab75b258a0cd904739f2dbf.11ea48f9728470a1b18b59f8dca312c5.ExternalServiceAccount",
  "sub": "11ea48f8dab75b258a0cd904739f2dbf.11ea48f9728470a1b18b59f8dca312c5.ExternalServiceAccount",
  "nbf": 0,
  "exp": 1588006343,
  "iat": 1576144302,
  "jti": "11ea4b22148ff077ae8561fde30129c5"
}

The Base64url representation of this is as follows:

eyJhdWQiOiJodHRwczovL2F1dGguZGlnaS5zZXJ2aWNlL2F1dGgvcmVhbG1zL3NlcnZpY2VhY2NvdW50cyIsImlzcyI6IjExZWE0OGY4ZGFiNzViMjU4YTBjZDkwNDczOWYyZGJmLjExZWE0OGY5NzI4NDcwYTFiMThiNTlmOGRjYTMxMmM1LkV4dGVybmFsU2VydmljZUFjY291bnQiLCJzdWIiOiIxMWVhNDhmOGRhYjc1YjI1OGEwY2Q5MDQ3MzlmMmRiZi4xMWVhNDhmOTcyODQ3MGExYjE4YjU5ZjhkY2EzMTJjNS5FeHRlcm5hbFNlcnZpY2VBY2NvdW50IiwibmJmIjowLCJleHAiOjE1ODgwMDYzNDMsImlhdCI6MTU3NjE0NDMwMiwianRpIjoiaWQxMSJ9

Signature

The JWT must be signed with a private key, using an RSA signature with SHA-256.

Sample JWT request

Pre-signing sample

{"alg":"RS256","typ":"JWT"}.


{


  "aud": "https://auth.alero.io/auth/realms/serviceaccounts",
  

"iss": "11ea48f8dab75b258a0cd904739f2dbf.11ea48f9728470a1b18b59f8dca312c5.ExternalServiceAccount",
  

"sub": "11ea48f8dab75b258a0cd904739f2dbf.11ea48f9728470a1b18b59f8dca312c5.ExternalServiceAccount",
  

"nbf": 0,


  "exp": 1588006343,


  "iat": 1576144302,


  "jti": "11ea4b22148ff077ae8561fde30129c5"


}.


[signature bytes]

Post-signing sample

eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJhdWQiOiJodHRwczovL2F1dGguZGlnaS5zZXJ2aWNlL2F1dGgvcmVhbG1zL3NlcnZpY2VhY2NvdW50cyIsImlzcyI6IjExZWE0OGY4ZGFiNzViMjU4YTBjZDkwNDczOWYyZGJmLjExZWE0OGY5NzI4NDcwYTFiMThiNTlmOGRjYTMxMmM1LkV4dGVybmFsU2VydmljZUFjY291bnQiLCJzdWIiOiIxMWVhNDhmOGRhYjc1YjI1OGEwY2Q5MDQ3MzlmMmRiZi4xMWVhNDhmOTcyODQ3MGExYjE4YjU5ZjhkY2EzMTJjNS5FeHRlcm5hbFNlcnZpY2VBY2NvdW50IiwibmJmIjowLCJleHAiOjE1ODgwMDYzNDMsImlhdCI6MTU3NjE0NDMwMiwianRpIjoiaWQxMSJ9.Vlvo6dlYi6CSZlW0bwJyZ9FPgKjvmLYmSk9UnRW5D02dkmgu2ML6p-s8B4_M4SV6DZ4reW4S61M_EvMR4tdwI2hQV5BRK5T4osQekCA8Z_MZhZAI0zWRtvagixVyWmpEpoBf1inuBdDVeKk0_Gc9cH63HtDhfa-RUUuZhCkxxDW_a7OzK-A3fpyuPuPnxIaNGrIqO8JQMomiwsSdGhvmslR-Py626aKrvoDe92haZbXNjNwKNtRayS-S_xi1TJs4IAJLmA3_Z_pXbXQr5QipA311tuBj6PYXkmZcsAmFltd9GAnxAzMw9FzYSHFELNlRz_s1dD12Xd7KnIvRri5Rfw

Perform an access token request

After generating the signed JWT, an application can use it to request an access token.

This access token request is an HTTPS POST request, and must include the following parameters:

Parameter	Description
grant_type	client_credentials
client_assertion_type	urn:ietf:params:oauth:client-assertion-type:jwt-bearer
client_assertion	A signed JWT that contains information for client authentication

Sample token request body

POST /auth/realms/serviceaccounts/protocol/openid-connect/token HTTP/1.1
Host: auth.alero.io
Content-Type: application/x-www-form-urlencoded
 
grant_type=client_credentials&client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer&client_assertion=eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJhdWQiOiJodHRwczovL2F1dGguYWxlcm8tcWEyLm5ldC9hdXRoL3JlYWxtcy9zZXJ2aWNlYWNjb3VudHMiLCJpc3MiOiIxMWVhMWY0OWE2YTk3YjA5YjIxMDYxY2E0NTg3Mjc0YS4xMWVhNDkwMTQ3OWEyMjc0OGE4NzZiMjk3MzBjNTQ2OS5FeHRlcm5hbFNlcnZpY2VBY2NvdW50Iiwic3ViIjoiMTFlYTFmNDlhNmE5N2IwOWIyMTA2MWNhNDU4NzI3NGEuMTFlYTQ5MDE0NzlhMjI3NDhhODc2YjI5NzMwYzU0NjkuRXh0ZXJuYWxTZXJ2aWNlQWNjb3VudCIsIm5iZiI6MCwiZXhwIjoxNTg4MDA2MzQzLCJpYXQiOjE1NzYxNDQzMDIsImp0aSI6IlRhbDMifQ.VYe4IDdO458G3xD2u-ybiFhHWBOhL5uSgktbU52vcN1dkyhFnHDGrBxZIhuDMxRW7brUt1zVxUOixSgPbPBP4VPIcvGk1OQNTNmGI16Nb7GVpZN5r4twYoZLiqjLQ6ojlyM0R5YH4pBLxz0pebqKa-iirx2IhNWua5j9nc3aDflW7WjA6bYSpwJjd0wXOhTYKrSWPI180FlTHwx1xEUO5IgbVZD7ntUHieMzPnEyHeGzoAOyFCaRLgJs87KIenvL7IJdDRjPfMZaf2IJ6DMdTLF0LdQIqq9S_rYUn-MK1X35bVfhSSOcz9e9vg_e8NyQ3FGaAfMw449MpivkyiVU4Q

If the JWT and access token request are properly formed and the service account has permission to perform the operation, the JSON response from the Authorization Server includes an access token

Sample JSON response

{
    "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJ4emhuNndHcnRRWm9DTlNhMm4xZHVTaS1IVXJFSzg1ZTQ1ZHZaQm5XY2pRIn0.eyJqdGkiOiJlMDhlYmZmZS1jYmZiLTQ3YzYtYTZlNy01M2Y0YzAxYmE4ZDgiLCJleHAiOjE1ODEwMTA5MzEsIm5iZiI6MCwiaWF0IjoxNTgxMDEwNjMxLCJpc3MiOiJodHRwczovL2F1dGguYWxlcm8tcWEyLm5ldC9hdXRoL3JlYWxtcy9zZXJ2aWNlYWNjb3VudHMiLCJhdWQiOiJhY2NvdW50Iiwic3ViIjoiYzE4ZTJlYjEtZGVhZC00YzU2LWI3NzUtYjhiNGIxNzA1NWQ4IiwidHlwIjoiQmVhcmVyIiwiYXpwIjoiMTFlYTFmNDlhNmE5N2IwOWIyMTA2MWNhNDU4NzI3NGEuMTFlYTQ5MDE0NzlhMjI3NDhhODc2YjI5NzMwYzU0NjkuRXh0ZXJuYWxTZXJ2aWNlQWNjb3VudCIsImF1dGhfdGltZSI6MCwic2Vzc2lvbl9zdGF0ZSI6ImZhNmFjNDFkLTJiMzUtNDJmMC04YjhkLTUzYTZhOGMwYzUwOSIsImFjciI6IjEiLCJyZWFsbV9hY2Nlc3MiOnsicm9sZXMiOlsib2ZmbGluZV9hY2Nlc3MiLCJ1bWFfYXV0aG9yaXphdGlvbiJdfSwicmVzb3VyY2VfYWNjZXNzIjp7ImFjY291bnQiOnsicm9sZXMiOlsibWFuYWdlLWFjY291bnQiLCJtYW5hZ2UtYWNjb3VudC1saW5rcyIsInZpZXctcHJvZmlsZSJdfX0sInNjb3BlIjoiZW1haWwgcHJvZmlsZSIsImVtYWlsX3ZlcmlmaWVkIjpmYWxzZSwiY2xpZW50SWQiOiIxMWVhMWY0OWE2YTk3YjA5YjIxMDYxY2E0NTg3Mjc0YS4xMWVhNDkwMTQ3OWEyMjc0OGE4NzZiMjk3MzBjNTQ2OS5FeHRlcm5hbFNlcnZpY2VBY2NvdW50IiwiY2xpZW50SG9zdCI6IjE5Mi4xNjguOS4yMzgiLCJwcmVmZXJyZWRfdXNlcm5hbWUiOiJzZXJ2aWNlLWFjY291bnQtMTFlYTFmNDlhNmE5N2IwOWIyMTA2MWNhNDU4NzI3NGEuMTFlYTQ5MDE0NzlhMjI3NDhhODc2YjI5NzMwYzU0NjkuZXh0ZXJuYWxzZXJ2aWNlYWNjb3VudCIsImNsaWVudEFkZHJlc3MiOiIxOTIuMTY4LjkuMjM4IiwiZW1haWwiOiJzZXJ2aWNlLWFjY291bnQtMTFlYTFmNDlhNmE5N2IwOWIyMTA2MWNhNDU4NzI3NGEuMTFlYTQ5MDE0NzlhMjI3NDhhODc2YjI5NzMwYzU0NjkuZXh0ZXJuYWxzZXJ2aWNlYWNjb3VudEBwbGFjZWhvbGRlci5vcmcifQ.BIGU80Zxt8cwvjWUyPBSxGUVu9wqE3S4Yc9S6NCpVFSFHXLGm0LkYcG7RRUUiC9ExPCzfTRgebSfO4VlxHcZzfXCy0uF6Ux6NEBruoIJGNOMatnAwCWyJRZu6C-wN1I2_YFwJly_-ZVsL5CfkY73nMyuBfJuxxmLe03VQf_KIMe6DjB2NJe7H9ZGG9H9zfcdmYNfE9viZVIy8iWfmqwioN5pn9YzrlRrAmoTEYnfDPxw0fKq_X6

AZEhB0DbiP03xLLO9uxAx4O4p1xaQkftY3XsKkT_ycG957wdRSxDl1ttjB_1nYGg2UStm9BO9pBAqIYt0IDGHO_6A14rcjnSBaw",
    "expires_in": 300,
    "refresh_expires_in": 1800,
    "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJmNjBkYWE5Zi1kYjlmLTQ5MTMtYjJlMC1mZWRiYjgzNDZiMGQifQ.eyJqdGkiOiJkZmU4OGI3OS1iOGM3LTRjYmEtYWIxNC0xNDQ2ZmJmMTk5MTAiLCJleHAiOjE1ODEwMTI0MzEsIm5iZiI6MCwiaWF0IjoxNTgxMDEwNjMxLCJpc3MiOiJodHRwczovL2F1dGguYWxlcm8tcWEyLm5ldC9hdXRoL3JlYWxtcy9zZXJ2aWNlYWNjb3VudHMiLCJhdWQiOiJodHRwczovL2F1dGguYWxlcm8tcWEyLm5ldC9hdXRoL3JlYWxtcy9zZXJ2aWNlYWNjb3VudHMiLCJzdWIiOiJjMThlMmViMS1kZWFkLTRjNTYtYjc3NS1iOGI0YjE3MDU1ZDgiLCJ0eXAiOiJSZWZyZXNoIiwiYXpwIjoiMTFlYTFmNDlhNmE5N2IwOWIyMTA2MWNhNDU4NzI3NGEuMTFlYTQ5MDE0NzlhMjI3NDhhODc2YjI5NzMwYzU0NjkuRXh0ZXJuYWxTZXJ2aWNlQWNjb3VudCIsImF1dGhfdGltZSI6MCwic2Vzc2lvbl9zdGF0ZSI6ImZhNmFjNDFkLTJiMzUtNDJmMC04YjhkLTUzYTZhOGMwYzUwOSIsInJlYWxtX2FjY2VzcyI6eyJyb2xlcyI6WyJvZmZsaW5lX2FjY2VzcyIsInVtYV9hdXRob3JpemF0aW9uIl19LCJyZXNvdXJjZV9hY2Nlc3MiOnsiYWNjb3VudCI6eyJyb2xlcyI6WyJtYW5hZ2UtYWNjb3VudCIsIm1hbmFnZS1hY2NvdW50LWxpbmtzIiwidmlldy1wcm9maWxlIl19fSwic2NvcGUiOiJlbWFpbCBwcm9maWxlIn0.khXF13Pb-e_LmMil0up-bGh_RJlDKC8p8FtyZ9ZWS6c",
    "token_type": "bearer",
    "not-before-policy": 0,
    "session_state": "fa6ac41d-2b35-42f0-8b8d-53a6a8c0c509"
}

Access tokens can be reused until during the duration noted in the expires_in value.

Call SWS APIs

After your application obtains an access token, use the token to make calls to a SWS API on behalf of a service account. Include the access token in a request to the API by including an Authorization: Bearer <AccessToken> HTTP header. In most cases, you can use a client library to set up your calls to SWS APIs.