Identity as a Service:Code integration

Scope

The environment is set up. For configuration instructions, see Prepare the environment.

Install the SDK

Run the go get command to add dependencies:

go get github.com/cloud-idaas/idaas-go-core-sdk

SDK initialization

The SDK reads the configuration file specified during environment setup to initialize the IDaaS configuration. The factory.Init() method automatically loads the configuration, performs validation, and prefetches the token. You do not need to manually call config.NewConfigReader().

package main

import (
    "fmt"
    "log"

    "github.com/cloud-idaas/idaas-go-core-sdk/factory"
)

func main() {
    // Initialize the factory. This automatically loads the configuration, validates it, and prefetches the token.
    // If no parameters are passed, the configuration file is loaded based on the default priority chain:
    //   1. Explicit file path (passed as a parameter)
    //   2. CLOUD_IDAAS_CONFIG_PATH environment variable
    //   3. Default path: ~/.cloud_idaas/client-config.json
    err := factory.Init()
    if err != nil {
        log.Fatalf("Initialization failed: %v", err)
    }

    fmt.Println("SDK initialization successful")
}

Important:

• All SDK features depend on the factory.Init() initialization method. You must complete the initialization first. Otherwise, attempts to retrieve IDaaSCredentialProvider or other components will fail and cause service interruptions.

• Initialization is idempotent. Calling the method again after initialization is complete does not rebuild the configuration. To re-initialize with a new configuration, call factory.Reset() first.

• Initialization includes configuration validation (Defaulting → Normalize → Validate). If the configuration is missing or validation fails, an error is reported immediately, causing a service interruption.

• At the end of initialization, the SDK attempts to prefetch an Access Token for the scope specified in the configuration file. This prefetch process uses a fault-tolerant pattern. If the prefetch fails, the SDK only records a WARN log and does not block the startup. This design prevents the process from being interrupted by network jitter during startup. In this case, the first call to GetCredential() triggers a refresh.

Get an access token

1. Obtain an IDaaS credential provider to retrieve an access token:

// Get the credential provider (automatically dispatched to the corresponding authentication flow based on the authnMethod in the configuration file)
provider, err := factory.GetIDaaSCredentialProvider()
if err != nil {
    log.Fatalf("Failed to get the credential provider: %v", err)
}

2. The access token is a Bearer token. Retrieve the credential with the GetCredential() method, and then retrieve the token string with the GetAccessToken() method:

// Get the credential
cred, err := provider.GetCredential()
if err != nil {
    log.Fatalf("Failed to get the credential: %v", err)
}

// Get the Bearer access token
accessToken := cred.GetAccessToken()

The scope format is AudienceIdentity|PermissionIdentity. This corresponds to the audience and permission identities for the target M2M server-side application. The scope specified in the configuration file is used by default. To access a different scope, modify the scope field in the configuration file.

Note: The combination of provider.GetCredential() and cred.GetAccessToken() in the Go SDK is equivalent to credentialProvider.getBearerToken() in the Java SDK and get_bearer_token() in the Python SDK. All these methods are used to retrieve a Bearer access token.

Recommendation for production environments: Use the GetCredentialWithContext(ctx) method in the request chain. This method supports context cancellation and deadline propagation to prevent long blocks during network failures. GetCredential() is internally equivalent to GetCredentialWithContext(context.Background()).

Complete code example

package main

import (
    "fmt"
    "log"

    "github.com/cloud-idaas/idaas-go-core-sdk/factory"
)

func main() {
    // Initialize the factory. This loads the configuration, validates it, and prefetches the token.
    err := factory.Init()
    if err != nil {
        log.Fatalf("initialization failed: %v", err)
    }

    // Get the IDaaS credential provider to obtain the access token for the scope specified in the configuration file.
    provider, err := factory.GetIDaaSCredentialProvider()
    if err != nil {
        log.Fatalf("Failed to get the credential provider: %v", err)
    }

    // Get the Bearer access token.
    cred, err := provider.GetCredential()
    if err != nil {
        log.Fatalf("Failed to get the credential: %v", err)
    }
    accessToken := cred.GetAccessToken()

    fmt.Println("Access Token:", accessToken)
}

Token exchange

Token exchange (RFC 8693) enables you to exchange a subject token for an access token with a different scope or audience. This is useful for scenarios such as token downgrading and inter-service calls.

package main

import (
    "fmt"
    "log"

    "github.com/cloud-idaas/idaas-go-core-sdk/factory"
    "github.com/cloud-idaas/idaas-go-core-sdk/provider"
)

func main() {
    // Initialize the factory. This automatically loads configurations, performs validation, and prefetches the token.
    err := factory.Init()
    if err != nil {
        log.Fatalf("initialization failed: %v", err)
    }

    // The subject token to be exchanged.
    subjectToken := "your_subject_token_here"

    // Get the token exchange provider. The factory reads the client secret from an environment variable.
    tokenExchangeProvider, err := factory.GetIDaaSTokenExchangeCredentialProvider()
    if err != nil {
        log.Fatalf("Failed to get token exchange provider: %v", err)
    }

    // Execute the token exchange. The parameters are encapsulated in the TokenExchangeRequest struct.
    cred, err := tokenExchangeProvider.ExchangeToken(provider.TokenExchangeRequest{
        SubjectToken: subjectToken,
        // ActorToken:   actorToken,     // Optional. Used for delegated authorization scenarios.
        // Scope:        "target_scope",  // Optional. Specify the target scope.
    })
    if err != nil {
        log.Fatalf("Token exchange failed: %v", err)
    }

    fmt.Println("Exchanged Access Token:", cred.GetAccessToken())
}