11/12/2024
Token Management: API Key, Basic Auth, JWT, OAuth
2.0
Overview
The token management applet facilitates secure token-based authentication for web API calls. By
generating unique tokens, securely passing them between clients and servers, and enforcing
authorization, it enhances both security and the user experience. Scalable and with token expiry
features, it's a key component ensuring efficient, safe, and seamless interactions.
Revision History
Rev No Date Description of Change
1.0 September 25, 2023 The initial release of the publication
1.1 November 12, 2024 Updated the screenshots
Table of Contents
l Token Management
l Prerequisites
l API Key
o Configuration and Generation of API Key
l Basic Auth
o Configuration of Basic Auth
l JWT
o Server Configuration
o Client Configuration
o Certificate Management
o Configuration and Generation of JWT
l OAuth 2.0
o IDP Configuration
1/23
o Configuration of OAuth 2.0 token
Token Management
Allows the management of tokens within the system.
These are the options available when the Token Management Applet is chosen.
l API Key
l Basic Auth
l JWT
l OAuth 2.0
Prerequisites
l CoLOS 6.4.2 or above
API Key
Allows securing the web services. To implement this, we need to configure both the server and cli-
ent sides. On the server, generate and manage API keys securely, associating them with specific cli-
ents or applications. On the client side, tools like Postman provide a mechanism to include the API
key in the HTTP request headers. This ensures that each API call is accompanied by a valid key for
authentication and authorization purposes.
Configuration and Generation of API Key
1. Open CoLOS Administrator on your device, and on the left panel, navigate to Browser-
>Control Panel>Token Management>API Key.
2/23
2. Enable the API Key plugin for token management; this will enable token support for the API
calls or disable the API Key plugin if you want to disable token support for the API calls.
3. On the API Key Generator Form, If you don’t want the token to expire, select the checkbox
next to No Expiry under Generate token.
3/23
4. If you want to keep the token’s expiration date, enter the API Key Expiry Date. Once done,
select Generate.
5. The token data is now generated, and you can copy the token data by selecting the Copy but-
ton. Click Close.
6. Open your Web API client app (e.g., Postman).
4/23
7. Use the token data for the Token Key header value (fixed header name value) as shown
below.
o The token key and value will now be passed along with the header and execute the
Web API calls.
o Web API calls include EnterpriseWebApi and CAT Integration Service.
o If the token is valid (i.e., all checks have passed and not expired), you will get a suc-
cessful response from the Web API calls.
Basic Auth
It involves sending a username and password with each request, encoded in Base64, to authen-
ticate clients.
Configuration of Basic Auth
1. Open CoLOS Administrator on your device, and on the left panel, navigate to Browser-
>Control Panel>Token Management>Basic Auth.
2. Enable the Basic Auth plugin for token management.
5/23
3. Basic Auth uses username and password as authentication modes.
4. The user should be one of the CoLOS native users, CAT users, or LDAP users.
5. Navigate to Browser>Control Panel>User Management to configure of users.
6. Open your Web API client app (e.g., Postman).
7. Put the valid username and password configured in the Postman basic authentication con-
figuration as shown below.
8. If the username and password are valid, you will get a success response from the Web API
calls.
Web API calls include EnterpriseWebApi and CAT Integration Service.
6/23
JWT
JWT (JSON Web Token) is a method for securing web services. JWT comprises three main parts:
the header, payload, and signature. The header specifies the token type and the signing algorithm
used. The payload contains claims about the user and additional data, while the signature is used to
verify the token’s authenticity and integrity. Together, these components form a compact and secure
way to exchange information between parties in web applications.
Server Configuration:
l Certificate Configuration: Generate or obtain a certificate. This certificate is used to sign and
verify JWT’s ensuring their integrity and authenticity.
l Configure the application to issue JWT’s upon successful authentication. Include user-spe-
cific data or claims in the token payload, sign it using the certificate’s private key, and specify
token expiration.
Client Configuration:
l For client-side integration, ensure that your client application is set up to receive and securely
store the public key from the certificate. This key is used to verify JWT’s received from the
server. Validate token signatures, check expiration, and extract claims to make authorized
API requests based on the token’s content.
Certificate Management:
CoLOS endpoint certificates can be managed under the:
CoLOS Administrator Control Panel > System > Properties > Certificate management.
There is an addition of endpoint called JWT:
7/23
8/23
Importing certificates is allowed only from the server computer and not from the cli-
ent computer. (This is done for security reasons, as it is not recommended to trans-
fer certificates with a private key over the network).
Self-signed certificates are commonly used in networks within a firewall and to test the deployments.
CoLOS creates the self-signed certificate right from the CoLOS installation. It is recommended to
use the certificates signed by the known signing authorities.
It is also common for large organizations to use their signing authority to create certificates.
Users can import the certificates using the CoLOS administrator and secure the endpoints using the
given certificate.
Configuration and Generation of JWT
1. Open CoLOS Administrator on your device, and on the left panel, navigate to Browser-
>Control Panel>Token Management>JWT.
2. Enable the JWT plugin for token management; this will enable token support for the API calls
or disable the JWT plugin if you want to disable token support for the API calls.
9/23
3. On the JWT Generator Form, configure the values under the generate token section by
adding the user name and user role.
4. If you don’t want the token to expire, select the checkbox next to No Expiry under Generate
Token.
10/23
5. If you want to keep the token’s expiration date, enter the token Expiry Date.
6. Once done, select Generate.
The token data is now generated, and you can copy the token data by selecting the Copy but-
ton.
7. Open your Web API client app (e.g., Postman).
8. Use the token data for the Bearer header prefix.
11/23
9. If the token is valid (i.e., all checks have passed and not expired), you will get a successful
response from the Web API calls.
OAuth 2.0
OAuth 2.0 is an industry-standard protocol for authorization. It allows applications to access user
data or perform actions on their behalf without exposing sensitive credentials.
IDP Configuration:
1. OKTA IDP Configuration
Create an Okta account: Sign up for an Okta account.
It's essential for the client to first create user profiles and groups before gen-
erating the access token.
Configuring Applications in OKTA
Adding Application in OKTA
In your Okta admin dashboard, add a new application and choose the “web” platform as
shown below.
1. Log in to the OKTA portal using an account with administrative rights (https://okta-
devok12.okta.com).
2. Go to the Applications tab and click Create App Integration.
12/23
3. Select OIDC - OpenID Connect as the Sign-in method, and Web Application as the
Application type. Click Next.
4. Enter the app name (e.g., CoLOS Web API (ODIC))
13/23
5. In General Settings, Click Edit and select Grant Type as Implicit (hybrid). Sign-in
redirect URIs and Sign-out redirect URIs as http://locahost:8080
Configure the necessary grant type configuration, like adding the cli-
ent credentials as a grant type
6. Select the radio button for "Allow everyone in your organization to access" and click
Save.
14/23
Result: New App is created.
7. Note down the Client ID and Client Secret to configure in Postman, as shown below:
8. Custom Scopes and Claims: Define custom scopes and claims for access control,
“groups.read” scopes, and “groups” claim to fetch the groups from the access token.
9. Goto Security>API>default.
15/23
10. Goto Scopes and click Add Scope.
16/23
11. Goto Claims and click Add claim.
17/23
12. Note down the Audience, Issuer URL, and Metadata URL to add in the OAuth 2.0
Configurator Form in CoLOS Administrator. Follow the below steps to find the above
fields from OKTA IDP.
13. In your OKTA admin dashboard, navigate to Security>API>Authorization Servers.
14. Go to the Authorization server; under this goto default, you will find the Audience,
Issuer, and Metadata URI as shown below.
18/23
15. Note down the Audience, Issuer URL and Metadata URL from the above mappings to
add in the OAuth 2.0 Configurator Form in CoLOS Administrator.
16. Access the metadata URI (e.g., use a web browser) – This URL typically points to an
XML file or a well-structured document that contains information about the IDP’s end-
points, certificates, and other relevant details.
17. From the above response shown note down
l authorization_endpoint - use this in postman configuration under the "Auth URL"
field.
l token_endpoint – use this in postman configuration under the “Access Token
URL” field.
19/23
Configuration of OAuth 2.0 token
1. Open CoLOS Administrator on your device, and on the left panel, navigate to Browser-
>Control Panel>Token Management>OAuth 2.0
.
2. Enable the OAuth 2.0 plugin for token management; this will enable token support for the API
calls, or disable the OAuth 2.0 plugin if you want to disable token support for the API calls
3. On the OAuth 2.0 Configurator Form, as shown below
4. Fill out the following mandatory fields:
20/23
l Audience: The application-defined unique identifier is the intended consumer of the
token.
l Group Attribute: The group attribute statement is used to fetch the user groups.
l Group Prefix: This is used to identify a role from the groups that begin with the given
‘prefix’.
l Issuer: The base URL in any OAuth 2.0 endpoint when authorizing against the identity
provider.
l Metadata URL: The metadata URL defines the format for clients to use to look up the
information needed to interact with a particular OAuth 2.0 server.
5. Once done, click OK.
The configuration data is now saved.
6. Open your Web API client app (e.g., Postman).
7. By selecting the Authorization type as OAuth 2.0, generate an access token by the con-
figuring the necessary parameters given in Postman. Click Clear Cookies.
21/23
8. Click Get New Access Token. Enter the OKTA Credentials. New Access Token is gen-
erated.
9. Use the token data for the OAuth2 header prefix.
The token value will now be passed and execute the Web API calls as shown below.
22/23
10. If the token is valid (i.e., all checks have passed and not expired), you will get a successful
response from the Web API calls.
11. Web API calls include EnterpriseWebAPI and CAT Integration Service.
23/23
