Alibaba Cloud Credentials for C++

English | 简体中文

Alibaba Cloud Credentials for C++

Alibaba Cloud Credentials for C++ is a tool that helps C++ developers manage their credentials.

Requirements

Compiler Requirements

Windows: Visual Studio 2015 or later
Linux: GCC 4.9 or later
macOS: Clang (Xcode Command Line Tools)

Build Tools

CMake: 3.10 or later (3.15+ recommended for Windows)
C++ Standard: C++11 or higher

System Requirements

Memory: 4GB or more recommended
Disk Space: At least 500MB available space

Dependencies

This library depends on darabonba-core, which requires the following system libraries:

OpenSSL: For encryption and network communication
- Windows: Install via vcpkg (vcpkg install openssl) or chocolatey (choco install openssl)
- Linux: sudo apt-get install libssl-dev (Ubuntu/Debian) or sudo yum install openssl-devel (CentOS/RHEL)
- macOS: brew install openssl
libcurl: For HTTP requests
- Windows: Install via vcpkg (vcpkg install curl)
- Linux: sudo apt-get install libcurl4-openssl-dev (Ubuntu/Debian) or sudo yum install libcurl-devel (CentOS/RHEL)
- macOS: Preinstalled or brew install curl
zlib: For compression (required by curl, especially for static builds)
- Windows: Install via vcpkg (vcpkg install zlib)
- Linux: sudo apt-get install zlib1g-dev (Ubuntu/Debian) or sudo yum install zlib-devel (CentOS/RHEL)
- macOS: Preinstalled or brew install zlib
uuid (Linux only): For UUID generation
- Ubuntu/Debian: sudo apt-get install uuid-dev
- CentOS/RHEL: sudo yum install libuuid-devel
- macOS: Not required (uses CoreFoundation framework)
- Windows: Not required (uses Windows UUID API)

Quick Install (All Dependencies):

# Ubuntu/Debian
sudo apt-get install -y libssl-dev libcurl4-openssl-dev zlib1g-dev uuid-dev

# CentOS/RHEL
sudo yum install -y openssl-devel libcurl-devel zlib-devel libuuid-devel

# macOS (Homebrew)
brew install openssl curl

# Windows (vcpkg)
vcpkg install openssl curl zlib

Installation

Linux/macOS

git clone https://github.com/aliyun/credentials-cpp.git
cd credentials-cpp
sh scripts/install.sh

Windows

Run the following command to clone code from GitHub via git-bash:

git clone https://github.com/aliyun/credentials-cpp.git

Build using Visual Studio:
- Create a cmake_build directory in the root directory
- Open CMake GUI, then:
  - Set Browse Source to the source code directory (credentials-cpp)
  - Set Browse Build to the build directory (cmake_build)
  - Click Configure
  - Click Generate to generate the VS solution
Build and Install C++ SDK:
- Go to the cmake_build directory and open alibabacloud_credentials.sln with Visual Studio
- Select Release configuration
- Check INSTALL option from Build -> Configuration Manager
- Build -> Build Solution

Quick Build

# Clone and build
git clone https://github.com/aliyun/credentials-cpp.git
cd credentials-cpp
mkdir build && cd build
cmake -S .. -B . -DCMAKE_BUILD_TYPE=Release
cmake --build . --config Release
cmake --install .

📖 For detailed build instructions, see BUILD.md | BUILD-zh-CN.md

Quick Examples

Before you begin, you need to sign up for an Alibaba Cloud account and retrieve your Credentials.

📚 For more examples, see examples/README.md | examples/README-zh-CN.md

Using Default Credentials Provider Chain (Recommended)

#include <alibabacloud/credentials/Client.hpp>
#include <iostream>

using namespace AlibabaCloud::Credentials;

int main() {
    // Use default credentials provider chain
    Client client;
    
    // Get credentials
    auto credential = client.getCredential();
    std::cout << "AccessKeyId: " << credential.getAccessKeyId() << std::endl;
    std::cout << "AccessKeySecret: " << credential.getAccessKeySecret() << std::endl;
    std::cout << "Type: " << credential.getType() << std::endl;
    
    return 0;
}

Using Specific Credential Type

#include <alibabacloud/credentials/Client.hpp>
#include <iostream>

using namespace AlibabaCloud::Credentials;

int main() {
    // Create config with AccessKey
    Models::Config config;
    config.setType("access_key")
          .setAccessKeyId("<your-access-key-id>")
          .setAccessKeySecret("<your-access-key-secret>");
    
    // Create client with config
    Client client(config);
    
    // Get credentials
    auto credential = client.getCredential();
    std::cout << "AccessKeyId: " << credential.getAccessKeyId() << std::endl;
    
    return 0;
}

Credential Types

Default Credentials Provider Chain

If you do not specify a credential type, the client will search for credentials in the following order:

Environment Variables: ALIBABA_CLOUD_ACCESS_KEY_ID and ALIBABA_CLOUD_ACCESS_KEY_SECRET
OIDC RAM Role: Configured via environment variables ALIBABA_CLOUD_ROLE_ARN, ALIBABA_CLOUD_OIDC_PROVIDER_ARN, and ALIBABA_CLOUD_OIDC_TOKEN_FILE
Configuration File: ~/.alibabacloud/credentials.ini or ~/.alibabacloud/credentials.json
ECS Instance RAM Role: Retrieved via ECS Instance Metadata Service (IMDS), if ALIBABA_CLOUD_ECS_METADATA is set
Credentials URI: Retrieved from URL specified by environment variable ALIBABA_CLOUD_CREDENTIALS_URI

Setting credentials via environment variables:

# Linux/macOS
export ALIBABA_CLOUD_ACCESS_KEY_ID="<your-access-key-id>"
export ALIBABA_CLOUD_ACCESS_KEY_SECRET="<your-access-key-secret>"

# Windows (PowerShell)
$env:ALIBABA_CLOUD_ACCESS_KEY_ID="<your-access-key-id>"
$env:ALIBABA_CLOUD_ACCESS_KEY_SECRET="<your-access-key-secret>"

# Windows (CMD)
set ALIBABA_CLOUD_ACCESS_KEY_ID=<your-access-key-id>
set ALIBABA_CLOUD_ACCESS_KEY_SECRET=<your-access-key-secret>

Setting credentials via configuration file (~/.alibabacloud/credentials.ini):

[default]
type = access_key
access_key_id = <your-access-key-id>
access_key_secret = <your-access-key-secret>

AccessKey

Setup access_key credential through User Information Management. It has full authority over the account, please keep it safe. Sometimes for security reasons, you cannot hand over a primary account AccessKey with full access to the developer of a project. You may create a sub-account RAM Sub-account, grant its authorization, and use the AccessKey of RAM Sub-account.

#include <alibabacloud/credentials/Client.hpp>

using namespace AlibabaCloud::Credentials;

int main() {
    Models::Config config;
    config.setType("access_key")
          .setAccessKeyId("<your-access-key-id>")
          .setAccessKeySecret("<your-access-key-secret>");
    
    Client client(config);
    
    auto credential = client.getCredential();
    printf("AccessKeyId: %s\n", credential.getAccessKeyId().c_str());
    printf("AccessKeySecret: %s\n", credential.getAccessKeySecret().c_str());
    
    return 0;
}

STS

Create a temporary security credential by applying Temporary Security Credentials (TSC) through the Security Token Service (STS).

#include <alibabacloud/credentials/Client.hpp>

using namespace AlibabaCloud::Credentials;

int main() {
    Models::Config config;
    config.setType("sts")
          .setAccessKeyId("<your-access-key-id>")
          .setAccessKeySecret("<your-access-key-secret>")
          .setSecurityToken("<your-security-token>");
    
    Client client(config);
    
    auto credential = client.getCredential();
    printf("AccessKeyId: %s\n", credential.getAccessKeyId().c_str());
    printf("AccessKeySecret: %s\n", credential.getAccessKeySecret().c_str());
    printf("SecurityToken: %s\n", credential.getSecurityToken().c_str());
    
    return 0;
}

RamRoleArn

By specifying RAM Role, the credential will be able to automatically request maintenance of STS Token. If you want to limit the permissions (How to make a policy) of STS Token, you can assign value for Policy.

#include <alibabacloud/credentials/Client.hpp>

using namespace AlibabaCloud::Credentials;

int main() {
    Models::Config config;
    config.setType("ram_role_arn")
          .setAccessKeyId("<your-access-key-id>")
          .setAccessKeySecret("<your-access-key-secret>")
          .setRoleArn("<your-role-arn>")
          .setRoleSessionName("<your-role-session-name>")
          // Optional: set policy, duration, and region
          .setPolicy("<your-policy>")
          .setDurationSeconds(3600)
          .setStsRegionId("cn-hangzhou");
    
    Client client(config);
    
    auto credential = client.getCredential();
    printf("AccessKeyId: %s\n", credential.getAccessKeyId().c_str());
    printf("AccessKeySecret: %s\n", credential.getAccessKeySecret().c_str());
    printf("SecurityToken: %s\n", credential.getSecurityToken().c_str());
    
    return 0;
}

OIDCRoleArn

By specifying OIDC Role, the credential will be able to automatically request maintenance of STS Token using OIDC Token.

#include <alibabacloud/credentials/Client.hpp>

using namespace AlibabaCloud::Credentials;

int main() {
    Models::Config config;
    config.setType("oidc_role_arn")
          .setRoleArn("<your-role-arn>")
          .setOidcProviderArn("<your-oidc-provider-arn>")
          .setOidcTokenFilePath("<path-to-oidc-token-file>")
          .setRoleSessionName("<your-role-session-name>")
          // Optional: set policy, duration, and region
          .setDurationSeconds(3600)
          .setStsRegionId("cn-hangzhou");
    
    Client client(config);
    
    auto credential = client.getCredential();
    printf("AccessKeyId: %s\n", credential.getAccessKeyId().c_str());
    printf("AccessKeySecret: %s\n", credential.getAccessKeySecret().c_str());
    printf("SecurityToken: %s\n", credential.getSecurityToken().c_str());
    
    return 0;
}

Or configure via environment variables:

export ALIBABA_CLOUD_ROLE_ARN="<your-role-arn>"
export ALIBABA_CLOUD_OIDC_PROVIDER_ARN="<your-oidc-provider-arn>"
export ALIBABA_CLOUD_OIDC_TOKEN_FILE="<path-to-oidc-token-file>"
export ALIBABA_CLOUD_ROLE_SESSION_NAME="<your-role-session-name>"

EcsRamRole

By specifying the role name, the credential will be able to automatically request maintenance of STS Token.

By default, the Credentials tool accesses the metadata server of ECS in security hardening mode (IMDSv2). If an exception is thrown, the Credentials tool switches to the normal mode (IMDSv1). You can configure the disableIMDSv1 parameter or the ALIBABA_CLOUD_IMDSV1_DISABLE environment variable to specify the exception handling logic:

false (default): The Credentials tool continues to obtain the access credential in normal mode (IMDSv1).
true: The exception is thrown and the Credentials tool continues to obtain the access credential in security hardening mode.

You can specify ALIBABA_CLOUD_ECS_METADATA_DISABLED=true to disable access from the Credentials tool to the metadata server of ECS.

#include <alibabacloud/credentials/Client.hpp>

using namespace AlibabaCloud::Credentials;

int main() {
    Models::Config config;
    config.setType("ecs_ram_role")
          .setRoleName("<your-ecs-role-name>")
          // Optional: disable IMDSv1 for enhanced security
          .setDisableIMDSv1(false);
    
    Client client(config);
    
    auto credential = client.getCredential();
    printf("AccessKeyId: %s\n", credential.getAccessKeyId().c_str());
    printf("AccessKeySecret: %s\n", credential.getAccessKeySecret().c_str());
    printf("SecurityToken: %s\n", credential.getSecurityToken().c_str());
    
    return 0;
}

Or configure via environment variable:

export ALIBABA_CLOUD_ECS_METADATA="<your-ecs-role-name>"

URLCredential

Get credentials by specifying a URL and the credential tool will automatically request this URL to obtain credentials.

#include <alibabacloud/credentials/Client.hpp>

using namespace AlibabaCloud::Credentials;

int main() {
    Models::Config config;
    config.setType("credentials_uri")
          .setCredentialsURL("<your-credentials-url>");
    
    Client client(config);
    
    auto credential = client.getCredential();
    printf("AccessKeyId: %s\n", credential.getAccessKeyId().c_str());
    printf("AccessKeySecret: %s\n", credential.getAccessKeySecret().c_str());
    printf("SecurityToken: %s\n", credential.getSecurityToken().c_str());
    
    return 0;
}

Or configure via environment variable:

export ALIBABA_CLOUD_CREDENTIALS_URI="<your-credentials-url>"

The response from the URL must be in the following format:

{
  "Code": "Success",
  "AccessKeyId": "<your-access-key-id>",
  "AccessKeySecret": "<your-access-key-secret>",
  "SecurityToken": "<your-security-token>",
  "Expiration": "2023-12-31T12:00:00Z"
}

BearerToken

If credential is required by the Cloud Call Centre (CCC), please apply for Bearer Token maintenance by yourself.

#include <alibabacloud/credentials/Client.hpp>

using namespace AlibabaCloud::Credentials;

int main() {
    Models::Config config;
    config.setType("bearer")
          .setBearerToken("<your-bearer-token>");
    
    Client client(config);
    
    auto credential = client.getCredential();
    printf("BearerToken: %s\n", credential.getBearerToken().c_str());
    
    return 0;
}

RsaKeyPair

By specifying the public key ID and the private key file, the credential will be able to automatically request maintenance of the AccessKey. Only Japan station is supported.

#include <alibabacloud/credentials/Client.hpp>

using namespace AlibabaCloud::Credentials;

int main() {
    Models::Config config;
    config.setType("rsa_key_pair")
          .setPublicKeyId("<your-public-key-id>")
          .setPrivateKeyFile("<path-to-private-key-file>");
    
    Client client(config);
    
    auto credential = client.getCredential();
    printf("AccessKeyId: %s\n", credential.getAccessKeyId().c_str());
    printf("AccessKeySecret: %s\n", credential.getAccessKeySecret().c_str());
    
    return 0;
}

Configuration

Config Parameters

Parameter	Type	Description
`type`	string	Credential type
`accessKeyId`	string	Access Key ID
`accessKeySecret`	string	Access Key Secret
`securityToken`	string	Security Token
`bearerToken`	string	Bearer Token
`roleArn`	string	RAM Role ARN
`roleSessionName`	string	Role session name
`policy`	string	Permission policy (JSON string)
`durationSeconds`	int64_t	Session duration in seconds (default: 3600)
`roleName`	string	ECS RAM role name
`oidcProviderArn`	string	OIDC Provider ARN
`oidcTokenFilePath`	string	Path to OIDC token file
`publicKeyId`	string	RSA public key ID
`privateKeyFile`	string	Path to RSA private key file
`credentialsURL`	string	URL to fetch credentials
`stsEndpoint`	string	STS endpoint (default: sts.aliyuncs.com)
`stsRegionId`	string	STS region ID
`regionId`	string	Region ID (default: cn-hangzhou)
`timeout`	int64_t	Read timeout in milliseconds (default: 5000)
`connectTimeout`	int64_t	Connection timeout in milliseconds (default: 10000)
`disableIMDSv1`	bool	Disable IMDSv1 for ECS metadata (default: false)
`enableVpc`	bool	Enable VPC endpoint (default: false)

Environment Variables

Variable	Description
`ALIBABA_CLOUD_ACCESS_KEY_ID`	Access Key ID
`ALIBABA_CLOUD_ACCESS_KEY_SECRET`	Access Key Secret
`ALIBABA_CLOUD_SECURITY_TOKEN`	Security Token
`ALIBABA_CLOUD_ROLE_ARN`	RAM Role ARN
`ALIBABA_CLOUD_OIDC_PROVIDER_ARN`	OIDC Provider ARN
`ALIBABA_CLOUD_OIDC_TOKEN_FILE`	Path to OIDC token file
`ALIBABA_CLOUD_ROLE_SESSION_NAME`	Role session name
`ALIBABA_CLOUD_ECS_METADATA`	ECS RAM role name
`ALIBABA_CLOUD_ECS_METADATA_DISABLED`	Disable ECS metadata service
`ALIBABA_CLOUD_IMDSV1_DISABLE`	Disable IMDSv1
`ALIBABA_CLOUD_CREDENTIALS_URI`	URL to fetch credentials
`ALIBABA_CLOUD_STS_REGION`	STS region
`ALIBABA_CLOUD_VPC_ENDPOINT_ENABLED`	Enable VPC endpoint

Issues

Submit Issue, Problems that do not meet the guidelines may be closed immediately.

Release Notes

Detailed changes for each version are recorded in the Release Notes.

License

Apache-2.0

Name		Name	Last commit message	Last commit date
Latest commit History 36 Commits
.github/workflows		.github/workflows
cmake		cmake
examples		examples
external		external
include/alibabacloud/credentials		include/alibabacloud/credentials
scripts		scripts
src		src
tests		tests
.clang-format		.clang-format
.codecov.yml		.codecov.yml
.gitignore		.gitignore
.travis.yml		.travis.yml
BUILD-zh-CN.md		BUILD-zh-CN.md
BUILD.md		BUILD.md
CHANGELOG.md		CHANGELOG.md
CMakeLists.txt		CMakeLists.txt
LICENSE		LICENSE
LICENSE.md		LICENSE.md
README-CN.md		README-CN.md
README-zh-CN.md		README-zh-CN.md
README.md		README.md

License

Licenses found

aliyun/credentials-cpp

Folders and files

Latest commit

History

Repository files navigation

Alibaba Cloud Credentials for C++

Table of Contents

Requirements

Compiler Requirements

Build Tools

System Requirements

Dependencies

Installation

Linux/macOS

Windows

Quick Build

Quick Examples

Using Default Credentials Provider Chain (Recommended)

Using Specific Credential Type

Credential Types

Default Credentials Provider Chain

AccessKey

STS

RamRoleArn

OIDCRoleArn

EcsRamRole

URLCredential

BearerToken

RsaKeyPair

Configuration

Config Parameters

Environment Variables

Issues

Release Notes

Related

License

About

Resources

License

Licenses found

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors 5

Uh oh!

Languages

Packages