Learn how to prepare your environment to use the Java SDK for obtaining an IDaaS application token. This topic covers JDK and Maven installation, dependency configuration, authentication methods, and configuration file parameters. - Identity as a Service

Prepare your environment to use the Java SDK for obtaining an IDaaS application token.

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>

Find the latest SDK version at https://mvnrepository.com/artifact/com.cloud-idaas/idaas-java-core-sdk

IDaaS supports OpenAPI authentication in scenarios like Function Compute. If you use Alibaba Cloud credentials (such as AccessKey pairs or STS tokens) to obtain an M2M client token, you must 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>

Find the latest version of the Alibaba Cloud authentication extension plugin at https://mvnrepository.com/artifact/com.cloud-idaas/idaas-java-core-alibabacloud-authentication-plugin

Specify the configuration file

The default path for the configuration file is ~/.cloud_idaas/client-config.json. If a path is not explicitly specified, the configuration file is retrieved from this path.

Specify the configuration file path by using either a Java system property or an environment variable:

Java system property name: cloud_idaas_config_path
Environment variable name: CLOUD_IDAAS_CONFIG_PATH

Example of configuring the 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

Example of configuring the environment variable:

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

Configuration file

The following code provides an example of the configuration file:

{
  "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 ID of your Cloud Identity and Access Management (IDaaS EIAM) instance.
clientId	Required. The ID of the IDaaS application. You can find this ID in the application's details.
issuer	Required. The issuer endpoint of the IDaaS EIAM instance. You can find this endpoint in any M2M application within the IDaaS EIAM instance.
tokenEndpoint	Required. The token endpoint of the IDaaS EIAM instance. You can find this endpoint 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, used 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. This parameter is used when obtaining an STS token or credentials for a RAM role 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. The other required fields in `authnConfiguration` depend on this value. For more information, see authnMethod and authnConfiguration mapping.
httpConfiguration	HTTP protocol settings. This object contains the following fields: `connectTimeout`: Optional. The maximum time, in milliseconds, to wait to establish a connection. Default value: 5000. `readTimeout`: Optional. After a connection is established, the maximum time, in milliseconds, to wait for data from the server. Default value: 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 name of the PKCS7 federated credential. You must first create a federated trust source. For more information, see Create a federated credential.
PKCS7	clientDeployEnvironment	Deployment environment. Currently, only `ALIBABA_CLOUD_ECS` is supported.
OIDC	applicationFederatedCredentialName	The name of the OIDC federated credential. You must first create a federated trust source. For more information, see Create a federated credential.
	clientDeployEnvironment	Deployment environment. Currently, only `KUBERNETES` is supported.
	oidcTokenFilePath	Optional. The path to the ServiceAccount token file. If this parameter is 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. The name of the environment variable that contains the path to the ServiceAccount token file. This parameter is used only if `oidcTokenFilePath` is not specified.
PCA	applicationFederatedCredentialName	The name of the PCA federated credential. You must first create a federated trust source. For more information, see Create a federated credential.
	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` is the name of the extension plugin. The only supported value is `alibabacloudPluginCredentialProvider`, which specifies the Alibaba Cloud OpenAPI authentication method. When you use Alibaba Cloud OpenAPI authentication, you need to complete the following configurations: Install the Alibaba Cloud authentication extension plugin. For more information, see Install the Java SDK. Configure RAM permissions. For more information, see OpenAPI authentication.

Configuration examples

The following sections provide configuration examples 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
  }
}