This page describes how to authenticate and authorize your calls to our APIs using standard OpenId Connect
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.
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
openssl genrsa -des3 -out private.pem 2048
OpenSSL will ask you for a passphrase that will be used to encrypt the private key file.
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.
This endpoint is rate-limited at 10 requests per seconds, which is more than enough when tokens are properly cached and reused until expiration.
Hitting the rate limit will cause HTTP 429 errors. It is recommended to implement a retry strategy to handle those errors (see also Troubleshooting API errors).
The process differs depending on whether you are using Public Key or Password authentication.
The basic steps are:
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.
Sign the JWT with the private key you generated earlier.
Send a client_credentials grant request to the authorization server token endpoint.
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
const { promisify } = require('util');
const { readFile } = require('fs');
const { sign } = require('jsonwebtoken');
const uuid = require('uuid');
const request = require('request-promise-native');
// ...
// replace this by the path of the PEM file containing your encrypted private key
// (c.f. "Create a Service Account" section)
const encryptedPrivateKeyPem = await promisify(readFile)('/path/to/my/pkcs8/key.pem', 'utf8');
// replace this by the passphrase you used when generating your private key
const encryptedPrivateKeyPassphrase = 'yourSecretPassphrase'
// replace this by the client ID of your service account
// (c.f. "Create a Service Account" section)
const serviceAccountClientId = 'your-client-id';
// replace this by your Attraqt tenant ID
const tenantId = "myTenantId";
const tokenEnpoint = `https://iam.attraqt.io/auth/realms/${tenantId}/protocol/openid-connect/token`;
const jwt = await promisify(sign)(
{},
{
key: encryptedPrivateKeyPem,
passphrase: encryptedPrivateKeyPassphrase
},
{
jwtid: uuid.v4(),
issuer: serviceAccountClientId,
subject: serviceAccountClientId,
audience: tokenEnpoint,
expiresIn: "1min",
algorithm: "RS256"
}
);
const credentials = await request({
method: 'POST',
uri: tokenEnpoint,
form: {
grant_type: 'client_credentials',
client_id: serviceAccountClientId,
client_assertion_type: 'urn:ietf:params:oauth:client-assertion-type:jwt-bearer',
client_assertion: jwt,
},
json: true,
});
const expiresIn = kcCredentials.expires_in; // seconds
const authorizationHeader = `${kcCredentials.token_type} ${kcCredentials.access_token}`;
// Cache the authorization header and use it in your
// calls to Attraqt APIs until its expiration
Java example
To work with the Java SDK, it is easier to convert your private key to the PKCS12 format:
// replace this by the path of the PKCS12 file containing your private key
File p12File = new File("/path/to/my/pkcs12/key.p12");
// replace this by the passphrase you used when generating your PKCS12 file
char[] p12Passphrase = "yourSecretPassphrase".toCharArray();
// replace this by the key alias you used when generating your PKCS12 file
String keyAlias = "your-key-alias";
// replace this by the client ID of your service account
// (c.f. "Create a Service Account" section)
ClientID serviceAccountClientId = new ClientID("your-client-id");
// replace this by your Attraqt tenant ID
String tenantId = "myTenantId";
URI tokenEnpoint = new URI("https://iam.attraqt.io/auth/realms/master/protocol/"+tenantId+"/token");
KeyStore store = KeyStore.getInstance("PKCS12");
try(InputStream p12stream = new FileInputStream(p12File)){
store.load(p12stream, p12Passphrase);
}
Key key = store.getKey(keyAlias, p12Passphrase);
HTTPResponse httpResponse = new TokenRequest(
tokenEnpoint,
new PrivateKeyJWT(
serviceAccountClientId,
tokenEnpoint,
JWSAlgorithm.RS256,
(RSAPrivateKey)key,
null,
null
),
new ClientCredentialsGrant()
).toHTTPRequest().send();
Object response = OIDCTokenResponseParser.parse(httpResponse);
if(response instanceof OIDCTokenResponse){
AccessToken accessToken = ((OIDCTokenResponse)response).getOIDCTokens().getAccessToken();
long expiresIn = accessToken.getLifetime(); // seconds
String authorizationHeader = accessToken.toAuthorizationHeader();
// Cache the authorization header and use it in your
// calls to Attraqt APIs until its expiration
} else {
String errorDescription = ((TokenErrorResponse)response).getErrorObject().getDescription()
System.err.println("Error getting access token: " + errorDescription);
}
Service accounts with the "Secret" authentication method can authenticate using basic HTTP authentication, using the client ID as username.
The identity server answers with a JSON document containing the following fields:
access_token: the access that must be used to authenticate API calls.
expires_in: time in seconds before the token expires.
Authenticating API calls
Calls to the Attraqt API must be authenticated with an Authorization header of type Bearer containing the acess token, for example:
curl -x GET \
https://items.attraqt.io/catalogs/active?tenant=${tenant}&environment=${environment}
-H "Authorization: Bearer ${access_token}"
You can use the access token as many times as you want before its expiration.
You must reuse access tokens as much as possible because calling the token endpoint is time and resource-consuming.
Access token expiration
Access tokens expire after a time given in the expires_in field of the identity server response. You will then need to get a new one using the same HTTP query.
