Attraqt
Search…
Authorization to APIs
This page describes how to authenticate and authorize your calls to our APIs using standard OpenId Connect and User-Managed Access flows

Create a service account

Service accounts provide an identity for your processes to access our APIs. They can authenticate themselves using either a Public Key or Password Authentication.
We recommend that you use Public key authentication which doesn't require sending secrets over the network.
Public Key Authentication
Password Authentication
You will need a private key to sign your access token requests, and a corresponding public key that our identity server will use to verify the signature.
Generate an RSA private key
1
openssl genrsa -des3 -out private.pem 2048
Copied!
OpenSSL will ask you for a passphrase that will be used to encrypt the private key file.
Generate the corresponding public key
1
openssl rsa -in private.pem -outform PEM -pubout -out public.pem
Copied!
Enter the private key passphrase when prompted.
Create the service account
Please reach out to your Technical Consultant to request a service account to be created. Specify that you chose Public Key Authentication and provide your public key. They will give you in return a Client ID and tenant ID that you will need in the following steps.
Please reach out to your Technical Consultant to request a service account to be created. Specify that you chose password authentication. They will provide you with a Client ID, secret and tenant ID that you will need in the following steps.

Obtaining access tokens

Access tokens can be obtained using the OpenId Connect Client Credentials grant.
The token endpoint to use is: https://iam.attraqt.io/auth/realms/${tenantId}/protocol/openid-connect/token where ${tenantId} is the identifier of your Attraqt tenant.
The process differs depending on whether you are using Public Key or Password authentication.
Public Key Authentication
Password Authentication
Service accounts with the JWT authentication method need to send a JWT signed with their private key to get access tokens, as described in RFC 7523.
The basic steps are:
  1. 1.
    Build a JWT with the following claims:
    • iss: your client ID (c.f. previous step)
    • sub: also your client ID
    • aud: the token endpoint
    • jti: a uniquely generated ID
    • exp: a rather short expiration time, one minute is more than enough.
  2. 2.
    Sign the JWT with the private key you generated earlier.
  3. 3.
    Send a client_credentials grant request to the authorization server token endpoint.
  4. 4.
    Use the access_token in the response to obtain Requesting Party Tokens that will be needed to authenticate your requests to Attraqt private APIs (see below).

Node.js example

1
const { promisify } = require('util');
2
const { readFile } = require('fs');
3
const { sign } = require('jsonwebtoken');
4
const uuid = require('uuid');
5
const request = require('request-promise-native');
6
7
// ...
8
9
// replace this by the path of the PEM file containing your encrypted private key
10
// (c.f. "Create a Service Account" section)
11
const encryptedPrivateKeyPem = await promisify(readFile)('/path/to/my/pkcs8/key.pem', 'utf8');
12
// replace this by the passphrase you used when generating your private key
13
const encryptedPrivateKeyPassphrase = 'yourSecretPassphrase'
14
// replace this by the client ID of your service account
15
// (c.f. "Create a Service Account" section)
16
const serviceAccountClientId = 'your-client-id';
17
// replace this by your Attraqt tenant ID
18
const tenantId = "myTenantId";
19
const tokenEnpoint = `https://iam.attraqt.io/auth/realms/${tenantId}/protocol/openid-connect/token`;
20
21
const jwt = await promisify(sign)(
22
{},
23
{
24
key: encryptedPrivateKeyPem,
25
passphrase: encryptedPrivateKeyPassphrase
26
},
27
{
28
jwtid: uuid.v4(),
29
issuer: serviceAccountClientId,
30
subject: serviceAccountClientId,
31
audience: tokenEnpoint,
32
expiresIn: "1min",
33
algorithm: "RS256"
34
}
35
);
36
37
const credentials = await request({
38
method: 'POST',
39
uri: tokenEnpoint,
40
form: {
41
grant_type: 'client_credentials',
42
client_id: serviceAccountClientId,
43
client_assertion_type: 'urn:ietf:params:oauth:client-assertion-type:jwt-bearer',
44
client_assertion: jwt,
45
},
46
json: true,
47
});
48
49
const accessToken = credentials.access_token
50
51
//use the accessToken to obtain Requesting Party Tokens
Copied!

Java example

To work with the Java SDK, it is easier to convert your private key to the PKCS12 format:
1
openssl pkcs12 -export -nocerts -inkey private.pem -out key.p12 -name your-key-alias
Copied!
And you can generate JWTs with Nimbus OAuth 2.0 SDK:
  • Apache Maven:
1
<dependency>
2
<groupId>com.nimbusds</groupId>
3
<artifactId>oauth2-oidc-sdk</artifactId>
4
<version>9.2</version>
5
</dependency>
Copied!
  • Gradle:
1
implementation 'com.nimbusds:oauth2-oidc-sdk:9.2'
Copied!
Sample Code
1
// replace this by the path of the PKCS12 file containing your private key
2
File p12File = new File("/path/to/my/pkcs12/key.p12");
3
// replace this by the passphrase you used when generating your PKCS12 file
4
char[] p12Passphrase = "yourSecretPassphrase".toCharArray();
5
// replace this by the key alias you used when generating your PKCS12 file
6
String keyAlias = "your-key-alias";
7
// replace this by the client ID of your service account
8
// (c.f. "Create a Service Account" section)
9
ClientID serviceAccountClientId = new ClientID("your-client-id");
10
// replace this by your Attraqt tenant ID
11
String tenantId = "myTenantId";
12
URI tokenEnpoint = new URI("https://iam.attraqt.io/auth/realms/master/protocol/"+tenantId+"/token");
13
14
KeyStore store = KeyStore.getInstance("PKCS12");
15
try(InputStream p12stream = new FileInputStream(p12File)){
16
store.load(p12stream, p12Passphrase);
17
}
18
Key key = store.getKey(keyAlias, p12Passphrase);
19
20
HTTPResponse httpResponse = new TokenRequest(
21
tokenEnpoint,
22
new PrivateKeyJWT(
23
serviceAccountClientId,
24
tokenEnpoint,
25
JWSAlgorithm.RS256,
26
(RSAPrivateKey)key,
27
null,
28
null
29
),
30
new ClientCredentialsGrant()
31
).toHTTPRequest().send();
32
33
Object response = OIDCTokenResponseParser.parse(httpResponse);
34
if(response instanceof OIDCTokenResponse){
35
String accessToken = ((OIDCTokenResponse)response).getOIDCTokens().getAccessToken().getValue();
36
///use the accessToken to obtain Requesting Party Tokens
37
} else {
38
String errorDescription = ((TokenErrorResponse)response).getErrorObject().getDescription()
39
System.err.println("Error getting access token: " + errorDescription);
40
}
Copied!
Service accounts with the "Secret" authentication method can authenticate using basic HTTP authentication, using the client ID as username.
Example using curl:
1
curl -X POST \
2
https://iam.attraqt.io/auth/realms/${tenantId}/protocol/openid-connect/token \
3
--user "your-client-id:your-client-secret" \
4
--data "grant_type=client_credentials"
Copied!
The response is a JSON document containing an access_token field that can be used to get Requesting Party Tokens.

Obtaining RPTs

Before calling Attraqt APIs, you need to add permissions to your access token using the User-Managed Access (UMA) 2.0 Grant. Access tokens containing permissions are called Requesting Party Tokens (RPTs).
A permission is a combination of:
  • an audience (e.g. attraqt-items)
  • an environment (e.g. env1)
  • a resource (e.g. ITEMS, TAG_RULES, SCHEMAS, CATALOGS etc.)
  • a scope (e.g. READ, WRITE)
You can find the audience, resource, and scope values needed in the API documentation.
RPTs are obtained by calling the same token endpoint as the step above. The audience must be set in the audience parameter, while the environment, resource, and scope must be set in the permission parameter in the format ENVIRONMENT_ID:RESOURCE_ID#SCOPE
For example, if you want to update items in the environment env1, use the following query:
1
curl -X POST \
2
https://iam.attraqt.io/auth/realms/${tenantId}/protocol/openid-connect/token \
3
-H "Authorization: Bearer ${access_token}" \
4
--data "grant_type=urn:ietf:params:oauth:grant-type:uma-ticket" \
5
--data "audience=attraqt-items" \
6
--data "permission=env1:ITEMS#WRITE"
Copied!
The permission parameter can be multi-valued, and the resulting RPT will contain all corresponding permissions. For example:
1
curl -X POST \
2
https://iam.attraqt.io/auth/realms/${tenantId}/protocol/openid-connect/token \
3
-H "Authorization: Bearer ${access_token}" \
4
--data "grant_type=urn:ietf:params:oauth:grant-type:uma-ticket" \
5
--data "audience=attraqt-items" \
6
--data "permission=env1:ITEMS#WRITE"
7
--data "permission=env1:CATALOGS#READ"
Copied!
The scope can be omitted, and the resulting RPT will contain permissions for all the scopes of the given resource that were granted to the service account. For example:
1
curl -X POST \
2
https://iam.attraqt.io/auth/realms/${tenantId}/protocol/openid-connect/token \
3
-H "Authorization: Bearer ${access_token}" \
4
--data "grant_type=urn:ietf:params:oauth:grant-type:uma-ticket" \
5
--data "audience=attraqt-items" \
6
--data "permission=env1:ITEMS"
Copied!
You can also omit the permission parameter entirely. The resulting RPT will contain all permissions that were granted to the service account on the service. For example:
1
curl -X POST \
2
https://iam.attraqt.io/auth/realms/${tenantId}/protocol/openid-connect/token \
3
-H "Authorization: Bearer ${access_token}" \
4
--data "grant_type=urn:ietf:params:oauth:grant-type:uma-ticket" \
5
--data "audience=attraqt-items"
Copied!
Don't use this method if you have granted a lot of permissions to your service account, the resulting RPT could be too big to fit in an HTTP authorization header.
We recommend limiting the number of permissions in an RPT as much as possible to mitigate the impact of token thefts.
The identity server answers with a JSON document containing the following fields:
  • access_token: the RPT that must be used to authenticate API calls.
  • expires_in: time in seconds before the RPT expires.
``

Authenticating API calls

Calls to the Attraqt API must be authenticated with an Authorization header of type Bearer containing the RPT, for example:
1
curl -x GET \
2
http://api.attraqt.io/items/my-catalog/my-context/my-type/my-item-id
3
-H "Authorization: Bearer ${rpt}"
Copied!
You can use the RPT as many times as you want before its expiration.
You must reuse RPTs as much as possible because calling the token endpoint is time and resource-consuming.

Access token expiration

Access tokens (including RPTs) expire after a time given in the expires_in field of the identity server response (typically 5 minutes). You will then need to get a new one using the same HTTP query.
Last modified 15d ago