Integration with API Key
Instead of using the SiX IDaaS & IAM console to manage your authentication/authorization assets in your tenancy. If your business model require you to manage such assets via the restful APIs, you can use the "Integration Key" to do so.
If you are developing your own APIs as introduced at Develop your own APIs based on IAM and will expose the access of these APIs to your customer, you can also use "Integration Key" to control the fine-grained access of these APIs.
Integration Key has the similar authorization model as IdP(Identity application) user, you can put it in different groups to set different permissions to it, you can also set the customized properties to it.
Interaction flows
See the Develop your own APIs based on IAM page and the Architecture section.
Basic Steps to access platform APIs
Use below steps to create Integration Key to access the platform or your own developed APIs.
WARNING
Integration Key need first authenticate itself util it can successfully access the platform APIs.
1. Create the Integration Key and grant authorization
Login SiX IDaaS & IAM console, navigate to "Service/Integration Key -> Create Integration Key" to create one Integration Key as instruction.
TIP
Integration Key need first authenticate itself util it can successfully access the platform APIs.
Download the RSA256 private key and copy the key id to your local PC for later usage.
WARNING
The RSA256 private key will only appear once on the console and it will NOT be persisted in the SiX IDaaS & IAM tenancy store.
Never expose this key for unintentional use as it act as the credentials for the Integration Key!
Grant the authorization by setting the properties of the key and/or putting it into different authorization groups as your design.
2. Authenticate the Integration Key and get access token
Generate the JWT using the RSA256 private key and key id
Use the private key you downloaded and the key id to create a JWT and sign it.
The sample code snippet to create JWT:
public static String createJwtBearerTokenWithRsaPrivateKey(String pemEncodedRSAPrivateKey, String keyId, int expiringInSeconds) throws JOSEException {
//Convert the x509 RSA private key in PEM format to JWK
JWK jwk = JWK.parseFromPEMEncodedObjects(pemEncodedRSAPrivateKey);
RSAKey rsaJWK = jwk.toRSAKey();
long expiringTime = new Date().getTime() + expiringInSeconds * 1000;
JWTClaimsSet claimsSet = new JWTClaimsSet.Builder()
.subject(keyId) //set the keyId as subject
.expirationTime(new Date(expiringTime))
.build();
SignedJWT signedJWT = new SignedJWT(
new JWSHeader.Builder(JWSAlgorithm.RS256).keyID(keyId).build(),
claimsSet);
//Create signer from the private key
JWSSigner signer = new RSASSASigner(rsaJWK);
signedJWT.sign(signer);
String jwt = signedJWT.serialize();
System.out.println(jwt);
return jwt;
}Use the JWT to exchange the access token
Use the "/oauth2/token" endpoint to exchange the JWT for access token, the authorization headers need to be as:
| Header Name | Header value |
|---|---|
| assertion | $JWT |
| grant_type | urn:ietf:params:oauth:grant-type:jwt-bearer |
3. Use the access token to access the platform APIs.
Put the access token in the "Authorization: Bearer ${access token}" request header, then to access the platform APIs listed in below:
Basic Steps to access your own APIs
1. Create the Integration Key and grant authorization
Login SiX IDaaS & IAM console, navigate to "Service/Integration Key -> Create Integration Key" to create one Integration Key as instruction.
TIP
Integration Key need first authenticate itself util it can successfully access the platform APIs.
Download the RSA256 private key and copy the key id to your local PC for later usage.
WARNING
The RSA256 private key will only appear once on the console and it will NOT be persisted in the SiX IDaaS & IAM tenancy store.
Never expose this key for unintentional usage as it act as the credentials for the Integration Key!
Grant the authorization by setting the properties of the key and/or putting it into different authorization groups as your design.
2. Authenticate the Integration Key and get access token
Generate the JWT using the RSA256 private key and key id
Use the private key you downloaded and the key id to create a JWT and sign it.
The sample code snippet to create JWT:
public static String createJwtBearerTokenWithRsaPrivateKey(String pemEncodedRSAPrivateKey, String keyId, int expiringInSeconds) throws JOSEException {
//Convert the x509 RSA private key in PEM format to JWK
JWK jwk = JWK.parseFromPEMEncodedObjects(pemEncodedRSAPrivateKey);
RSAKey rsaJWK = jwk.toRSAKey();
long expiringTime = new Date().getTime() + expiringInSeconds * 1000;
JWTClaimsSet claimsSet = new JWTClaimsSet.Builder()
.subject(keyId) //set the keyId as subject
.expirationTime(new Date(expiringTime))
.build();
SignedJWT signedJWT = new SignedJWT(
new JWSHeader.Builder(JWSAlgorithm.RS256).keyID(keyId).build(),
claimsSet);
//Create signer from the private key
JWSSigner signer = new RSASSASigner(rsaJWK);
signedJWT.sign(signer);
String jwt = signedJWT.serialize();
System.out.println(jwt);
return jwt;
}Use the JWT to exchange the access token
Use the "/oauth2/token" endpoint to exchange the JWT for access token, the authorization headers need to be as:
| Header Name | Header value |
|---|---|
| assertion | $JWT |
| grant_type | urn:ietf:params:oauth:grant-type:jwt-bearer |
3. Use the access token to access the your own APIs.
Put the access token in your APIs request e.g. in the headers then invoke your own developing APIs.
TIP
Before allowing the APIs access, your resource server need to validate the authenticity of access token first, for more info, please see:
Validate the access token via the JWK
For the access to the platform APIs, this validation will be done out of box.