IDaaS Java SDK environment preparation and setup - Identity as a Service

Install the required dependencies and configure authentication to use the IDaaS Java SDK for obtaining application tokens.

Environment requirements

Install JDK 1.8 or later.
Install Maven.

Install the Java SDK

Add the following dependency to your pom.xml file.

<dependency>
  <groupId>com.cloud-idaas</groupId>
  <artifactId>idaas-java-core-sdk</artifactId>
  <!-- Replace the version number with the latest version of the SDK -->
  <version>0.0.4-beta</version>
</dependency>

Latest SDK version: https://mvnrepository.com/artifact/com.cloud-idaas/idaas-java-core-sdk

If you use Alibaba Cloud credentials (AccessKey pairs or STS tokens) to obtain an M2M client token, such as in Function Compute scenarios, also add the Alibaba Cloud authentication extension plugin to your pom.xml file.

<dependency>
  <groupId>com.cloud-idaas</groupId>
  <artifactId>idaas-java-core-alibabacloud-authentication-plugin</artifactId>
  <!-- Replace the version number with the latest version of the Alibaba Cloud authentication extension plugin -->
  <version>0.0.1-beta</version>
</dependency>

Latest plugin version: https://mvnrepository.com/artifact/com.cloud-idaas/idaas-java-core-alibabacloud-authentication-plugin

Specify the configuration file

The default configuration file path is ~/.cloud_idaas/client-config.json.

Override the path with a Java system property or environment variable:

Java system property name: cloud_idaas_config_path
Environment variable name: CLOUD_IDAAS_CONFIG_PATH

Java system property:

-Dcloud_idaas_config_path=/.../client-config.json

// In a Spring Boot project, you can place the configuration file in the src/main/resources/ directory and reference it by using the classpath: prefix.
-Dcloud_idaas_config_path=classpath:client-config.json

Environment variable:

CLOUD_IDAAS_CONFIG_PATH=/.../client-config.json

Configuration file

Configuration file example:

{
  "idaasInstanceId": "idaas_xxx",      
  "clientId": "app_xxx",               
  "issuer":"https://xxx/api/v2/iauths_system/oauth2",               
  "tokenEndpoint": "https://xxx/api/v2/iauths_system/oauth2/token",
  "scope": "api.example.com|read:file",
  "openApiEndpoint":"eiam.[region_id].aliyuncs.com",
  "developerApiEndpoint":"eiam-developerapi.[region_id].aliyuncs.com",
  "authnConfiguration": {
    "identityType": "CLIENT",
    "authnMethod": "CLIENT_SECRET_POST",
    "clientSecretEnvVarName": "IDAAS_CLIENT_SECRET"
  },
  "httpConfiguration": {
    "connectTimeout": 5000,
    "readTimeout": 10000
  }
}

Parameters

Parameter	Description
idaasInstanceId	Required. The IDaaS EIAM instance ID.
clientId	Required. The IDaaS application ID, found in the application details.
issuer	Required. The issuer endpoint, available in any M2M application within the IDaaS EIAM instance.
tokenEndpoint	Required. The token endpoint, available in any M2M application within the IDaaS EIAM instance.
scope	Required. Specifies the audience identifier and permission identifier for the target M2M server-side application, in the format `Audience Identifier\|Permission Identifier`. When obtaining an STS token or credentials for a RAM role managed by IDaaS, this parameter must be set to `urn:cloud:idaas:pam\|.all`, which is a built-in scope for IDaaS.
openApiEndpoint	Optional. The IDaaS OpenAPI endpoint for OpenAPI authentication. You can obtain the service endpoint from the Cloud Identity and Access Management (IDaaS EIAM) - Alibaba Cloud OpenAPI Developer Portal. If your application is deployed in an Alibaba Cloud VPC in the same region as the IDaaS instance, you can use the internal VPC address.
developerApiEndpoint	Optional. The DeveloperAPI endpoint of IDaaS, used when obtaining an STS token or RAM role credentials managed by IDaaS. You can obtain the service endpoint from the Cloud Identity and Access Management (IDaaS EIAM) - Alibaba Cloud OpenAPI Developer Portal. If your application is deployed in an Alibaba Cloud VPC in the same region as the IDaaS instance, you can use the internal VPC address.
authnConfiguration	`identityType`: Optional. The default value is `CLIENT`. Currently, only `CLIENT` is supported, which indicates that the M2M client application authenticates as a machine identity. `authnMethod`: Required. The authentication method. Required fields in `authnConfiguration` vary by this value, as listed in the authnMethod and authnConfiguration mapping table.
httpConfiguration	HTTP protocol settings: `connectTimeout`: Optional. Maximum connection establishment time in milliseconds. Default: 5000. `readTimeout`: Optional. Maximum time to wait for server response data in milliseconds. Default: 10000.

authnMethod and authnConfiguration mapping

authnMethod	Required fields	Field description
CLIENT_SECRET_BASIC	clientSecretEnvVarName	The name of the environment variable that contains the client secret of the M2M client application.
CLIENT_SECRET_POST
CLIENT_SECRET_JWT
PRIVATE_KEY_JWT	privateKeyEnvVarName	The name of the environment variable that contains the private key of the M2M client application.
PKCS7	applicationFederatedCredentialName	The PKCS7 federated credential name. First create a federated credential as a trust source.
PKCS7	clientDeployEnvironment	Deployment environment. Only `ALIBABA_CLOUD_ECS` is supported.
OIDC	applicationFederatedCredentialName	The OIDC federated credential name. First create a federated credential as a trust source.
	clientDeployEnvironment	Deployment environment. Only `KUBERNETES` is supported.
	oidcTokenFilePath	Optional. Path to the ServiceAccount token file. If not set, the SDK reads the path from the environment variable specified by `oidcTokenFilePathEnvVarName`. If neither is set, the SDK uses the default Kubernetes path: /var/run/secrets/kubernetes.io/serviceaccount/token.
	oidcTokenFilePathEnvVarName	Optional. Environment variable name containing the ServiceAccount token file path. Used only if `oidcTokenFilePath` is not specified.
PCA	applicationFederatedCredentialName	The PCA federated credential name. First create a federated credential as a trust source.
	clientX509Certificate	The end-entity certificate, in the following format: -----BEGIN CERTIFICATE----- xxx -----END CERTIFICATE-----
	x509CertChains	A list of intermediate certificates. Concatenate multiple certificates with newline characters. The format is as follows: -----BEGIN CERTIFICATE----- xxx -----END CERTIFICATE----- -----BEGIN CERTIFICATE----- xxx -----END CERTIFICATE-----
	privateKeyEnvVarName	The name of the environment variable that contains the private key of the M2M client application.
PLUGIN	pluginName	`pluginName`: The extension plugin name. The only supported value is `alibabacloudPluginCredentialProvider`, which enables Alibaba Cloud OpenAPI authentication. To use this method: Install the Alibaba Cloud authentication extension plugin. Configure RAM permissions as described in OpenAPI authentication.

Configuration examples

The following examples show configurations for different authentication methods.

Example: Client secret credential

{
  "idaasInstanceId": "idaas_xxx",      
  "clientId": "app_xxx",               
  "issuer":"https://xxx/api/v2/iauths_system/oauth2",               
  "tokenEndpoint": "https://xxx/api/v2/iauths_system/oauth2/token",
  "scope": "api.example.com|read:file",
  "authnConfiguration": {
    "identityType": "CLIENT",
    "authnMethod": "CLIENT_SECRET_BASIC",
    "clientSecretEnvVarName": "IDAAS_CLIENT_SECRET"
  },
  "httpConfiguration": {
    "connectTimeout": 5000,
    "readTimeout": 10000
  }
}

Example: Public-private key credential

{
  "idaasInstanceId": "idaas_xxx",      
  "clientId": "app_xxx",               
  "issuer":"https://xxx/api/v2/iauths_system/oauth2",               
  "tokenEndpoint": "https://xxx/api/v2/iauths_system/oauth2/token",
  "scope": "api.example.com|read:file",
  "authnConfiguration": {
    "identityType": "CLIENT",
    "authnMethod": "PRIVATE_KEY_JWT",
    "privateKeyEnvVarName": "ENV_PRIVATE_KEY"
  },
  "httpConfiguration": {
    "connectTimeout": 5000,
    "readTimeout": 10000
  }
}

Example: PKCS7 federated credential

{
  "idaasInstanceId": "idaas_xxx",      
  "clientId": "app_xxx",               
  "issuer":"https://xxx/api/v2/iauths_system/oauth2",               
  "tokenEndpoint": "https://xxx/api/v2/iauths_system/oauth2/token",
  "scope": "api.example.com|read:file",
  "authnConfiguration": {
    "identityType": "CLIENT",
    "authnMethod": "PKCS7",
    "applicationFederatedCredentialName": "your_pkcs7_federated_credential_name",
    "clientDeployEnvironment": "ALIBABA_CLOUD_ECS"
  },
  "httpConfiguration": {
    "connectTimeout": 5000,
    "readTimeout": 10000
  }
}

Example: OIDC federated credential

{
  "idaasInstanceId": "idaas_xxx",      
  "clientId": "app_xxx",               
  "issuer":"https://xxx/api/v2/iauths_system/oauth2",               
  "tokenEndpoint": "https://xxx/api/v2/iauths_system/oauth2/token",
  "scope": "api.example.com|read:file",
  "authnConfiguration": {
    "identityType": "CLIENT",
    "authnMethod": "OIDC",
    "applicationFederatedCredentialName": "your_oidc_federated_credential_name",
    "clientDeployEnvironment": "KUBERNETES",
    "oidcTokenFilePath": "/var/run/secrets/.../token",
    "oidcTokenFilePathEnvVarName": "ENV_OIDC_TOKEN_FILE_PATH"
  },
  "httpConfiguration": {
    "connectTimeout": 5000,
    "readTimeout": 10000
  }
}

Example: PCA federated credential

{
  "idaasInstanceId": "idaas_xxx",      
  "clientId": "app_xxx",               
  "issuer":"https://xxx/api/v2/iauths_system/oauth2",               
  "tokenEndpoint": "https://xxx/api/v2/iauths_system/oauth2/token",
  "scope": "api.example.com|read:file",
  "authnConfiguration": {
    "identityType": "CLIENT",
    "authnMethod": "PCA",
    "applicationFederatedCredentialName": "your_pca_federated_credential_name",
    "clientX509Certificate": "-----BEGIN CERTIFICATE-----\nxxxxxx\n-----END CERTIFICATE-----",
    "x509CertChains": "-----BEGIN CERTIFICATE-----\nxxxxxx\n-----END CERTIFICATE-----\n-----BEGIN CERTIFICATE-----\nxxxxxx\n-----END CERTIFICATE-----",
    "privateKeyEnvVarName": "ENV_PRIVATE_KEY"
  },
  "httpConfiguration": {
    "connectTimeout": 5000,
    "readTimeout": 10000
  }
}

Example: OpenAPI authentication

{
  "idaasInstanceId": "idaas_xxx", 
  "clientId": "app_xxx", 
  "issuer":"https://xxx/api/v2/iauths_system/oauth2", 
  "tokenEndpoint": "https://xxx/api/v2/iauths_system/oauth2/token",
  "scope": "api.example.com|read:file",
  "openApiEndpoint":"eiam.[region_id].aliyuncs.com",
  "authnConfiguration": {
    "identityType": "CLIENT",
    "authnMethod": "PLUGIN",
    "pluginName": "alibabacloudPluginCredentialProvider"
  },
  "httpConfiguration": {
    "connectTimeout": 5000,
    "readTimeout": 10000
  }
}