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"
}

Prepare to make an API call

After you create the .json file in the Secure Web Sessions 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. For more information, see Create a JSON Web Token (JWT).
Request an access token from the token endpoint of the Secure Web Sessions Authorization Server. For more information, see Access token request.
Handle the JSON response that the Authorization Server returns.
Call APIs using the Access Token received from the Authorization Server. For more information, see Call Secure Web Sessions APIs

Create a JSON Web Token (JWT)

Secure Web Sessions 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 Secure Web Sessions 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 Secure Web Sessions 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. Secure Web Sessions validates the signature and the payload of the assertion.

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). We recommend to avoid any impact on the security of your application by using libraries that abstract the cryptography away from your application code.

JWT structure

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	ü
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

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 Secure Web Sessions APIs

After your application obtains an access token, use the token to make calls to a Secure Web Sessions 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 Secure Web Sessions APIs.