Authentication
Every request to the Coverity on Polaris API must be authenticated with a JSON web token (JWT). The JWT can be retrieved in three ways:
- Email and password
- Single sign-on (SSO)
- API token
API tokens are the best way to generate the JWT, because they last longer and are returned directly in the response body, rather than in a cookie.
You can create your first API token through the web application; or, if you are setting up a service account which cannot access the web application, you can create the API token through the API.
Retrieve a JWT by Email and Password
If SSO is not enabled, authenticate with your registered email and password using the
/auth/authenticate API endpoint. For all accounts except service accounts,
this generates an access_token cookie that is the JWT. For service accounts, the JWT is
returned in the body of the response.
Request:
curl -X POST -c - \
https://subdomain.cop.blackduck.com/api/auth/authenticate \
-H 'Accept:application/json' \
-H 'Content-Type:application/x-www-form-urlencoded' \
-d "email=test@example.com&password=hunter2"
Response:
#HttpOnly_subdomain.cop.blackduck.com FALSE / TRUE 1573848352 access_token {jwt string}
subdomain.cop.blackduck.com FALSE / TRUE 1573848352 access_token_exp_sec 3600
#HttpOnly_subdomain.cop.blackduck.com FALSE / TRUE 1573848352 private_csrf_token {string}
subdomain.cop.blackduck.com FALSE / TRUE 1573848352 csrf_token {string}
subdomain.cop.blackduck.com FALSE / TRUE 1573848352 organizationname {string}
Response -- as a service account in the response body:
{
"jwt" : "string"
}
Retrieve a JWT using Single Sign-On
The Coverity on Polaris platform uses SAML 2.0 for SSO integration. If your organization uses SSO, authenticate with the SSO provider in your browser to receive a JWT. After that, you can inspect the issued cookie to retrieve their JWT, or create an API token.
If you are accessing the API outside of a web browser; for example, using the command line, you should create an API token as explained below. Service accounts can bypass SSO by authenticating with their registered email and password.
Retrieving a JWT by Using an API Token
The API token, also known as an access token and personal access token, is the best method of authentication when using the Coverity on Polaris API to retrieve a JWT.
Store your API token securely; it cannot be retrieved by Coverity on Polaris. API tokens can be revoked by the user at any time.
To generate your first API token, authenticate with a registered email and password. Then use the resulting short-term JWT to generate the API token. After that, you can use the API token to retrieve a long-lasting JWT whenever you want to access the API.
This figure describes the process:
Request: Creating the API token
$ curl -X POST \
https://subdomain.cop.blackduck.com/api/auth/v1/apitokens \
-H 'Accept: application/vnd.api+json' \
-H 'Authorization: Bearer {JWT}' \
-H 'Content-Type: application/vnd.api+json' \
-d '{"data":{"attributes":{"name":"mynewtoken"},"type":"apitokens"}}'
Response: The value of the data.attributes ["access-token"] field is the newly generated API token.
{
"data": {
"type": "apitokens",
"id": "string",
"attributes": {
"name": "string",
"access-token": "string",
"revoked": false,
"date-created": "YYYY-MM-DDThh:mm:ss.SSS+0000"
},
"relationships": {
"owner": {
"links": {
<snip>
},
"data": {
"type": "users",
"id": "string"
}
}
},
"links": {
<snip>
}
},
"included": [ ]
}
Request: Authenticating with an API Token
$ curl -X POST \
https://subdomain.cop.blackduck.com/api/auth/v1/authenticate \
-H 'Accept: application/json' \
-H 'Content-Type: application/x-www-form-urlencoded' \
-d accesstoken={insert api token}
Response: When authenticating with an API token the JWT is returned in the response body.
{
"jwt" : "string"
}
JSON Web Tokens (JWT)
JSON Web Tokens are the primary credentials used for authentication with the API. The JWT can be presented to Coverity on Polaris either as a bearer token or in a cookie.
Header: Authorization: Bearer {JWT}
Cookie: access_token: {JWT}
Security: A new JWT is issued every time you:
- Submit your email and password, or
- Present an API token to the
/auth/authenticateAPI endpoint, or - Successfully authenticate with your single sign-on provider.
Expiration: Every JWT has an expiration, calculated in seconds since Unix epoch time. JWTs issued by email/password and SSO authentication expire after 1 hour. JWTs issued by API token authentication expire after 12 hours.
Decoding: JWTs use Base64 URL encoding. There are several online tools to copy and paste JWTs for easy decoding, such as jwt.io and jwt.ms.
Service Accounts
Service accounts can bypass SSO authentication by using a registered email and password. Note that they are restricted to automated interactions between the API and their approved IP addresses.