Develop your own APIs based on IAM

SiX IDaaS & IAM provides a multi-tenants authorization model to expose its capabilities to customers(developers) to build their own secured APIs.

Customers(developers) can use the "hierarchical organization", "customized role/permission", "group" and "customized properties" etc. to create the APIs to meet their specific requirements without the need to implement the complex authorization model by themselves.

Architecture

Basic Steps

According to the architecture and by leveraging below steps, customers(developers) can build their own secured APIs quickly.

1. Create the Identity App User or Integration Key

For Identity App User

The IdP created by SiX IDaaS & IAM supports the OIDC/OAuth2 out of the box, after you create the IdP, you are supposed to use an OIDC client to interact with the SiX IDaaS & IAM. The client will handle the authorization flow e.g. authorization_code grant flow automatically for your application, more info please see:

Create IdP for SPA

Create IdP for Native App

The IdP created by SiX IDaaS & IAM can be configured to federate with Wechat miniapp owned by the same customer, after the miniapp user authenticate with the authentication server from Wechat platform, the same user will be granted the access token generated from SiX IDaaS & IAM, one shadow user is created automatically for this miniapp user, more info please see:

Create IdP for Wechat Miniapp

For Integratin Key

SiX IDaaS & IAM extends its capability to create integration key which underhood is a RSA256 key pairs, customers(developers) can use the key to exchange the access token then use them to access the APIs, more info please see:

Integration with API Key

2. Authenticate the accessing entities and get the access token

Please use the links in 1. Create the Identity App User or Integration Key to know how to get the access token for the accessing entities.

3. Retrieve the authorization config for accessing entites

After the accessing entities was created, you can use the console to assign the authorization to them, for example put the app user or integration key in some customized groups or set the differentiated properties for the entities.

One authorization assignment sample is as below, note the section hightlighted in the JWT(access token) claims.

{
  "sub": "13888888888",
  "aud": "iot_sample_client",
  "nbf": 1728714570,
  "role": [
    {
      "ROLE_customer-role": [
        "perm-read-travels"
      ]
    }
  ],
  "org": {
    "level": 2,
    "orgId": "0a2a0090-8bf6-1c88-818b-feb6072c00e1"
  },
  "openId": "0a2a00f9-8faf-17bf-818f-aff3de430000",
  "scope": [
    "openid",
    "profile"
  ],
  "iss": "https://08d7db.app.shuhenglianchang.com",
  "property": [
    {
      "name": "custom-prop",
      "value": "123456"
    },
    {
      "name": "salesforce_fed_id",
      "value": "aaabbbccc"
    }
  ],
  "exp": 1728732570,
  "iat": 1728714570,
  "jti": "265181fa-9228-4b39-bb58-fe9061208d20"
}

4. Access APIs with access token

After you get the access token, you can use the access token(JWT) to invoke your developed APIs, for example you can put the token in the restful API request header.

5. Validate the access token via the JWK

After you get the JWK, your resource server can use it to validate the JWT(access token).

For Identity App User

For each of IdP created in SiX IDaaS & IAM, one sub-domain will be assigned to the IdP, you can check the JWK information in the ".well-known/openid-configuration" endpoint.

TIP

One sample IdP well-known endpoint: .well-known

One sample IdP jwk endpoint: jwk

For Integratin Key

For the integration key, please use the JWK from the platform.

TIP

Platform well-known endpoint: .well-known

Platform jwk endpoint: jwk

6 Verify claims (Authz check)

Your resource server can verify the claims encapsulated in the JWT(access token).

Our recommended approach is to convert the claims uniformly into your API function invocation interceptor and then interpret the permissions like the case shown in the example below.

Permission based authorization

//The accessing entity should have the permission to update the specific "resource" entity.
@PreAuthorize(hasPermission(#resourceId, 'resource', 'update'))
public Map<String, Object> resource(String resourceId) {
    //the implementation of the API
}

Property(Attribute) based authorization

//The accessing entity should have the property(six_iot_product = #resourceId) and property(purpose = device_reg) set in the claims to access the API.
@PreAuthorize(@attributeMethodSecurity.matchAttributeValue(authentication, #resourceId, 'six_iot_product') and @attributeMethodSecurity.matchAttributeValue(authentication, 'device_reg', 'purpose')) 
public Map<String, Object> controller(String resourceId) {
    //the implementation of the API
}