To set up multi-factor authentication on your OUTSCALE account:

  1. You need to upload a Certificate Authority (CA) which will serve as the anchor for a chain of trust.

  2. You then need to configure API access rules to require that all API requests provide a client certificate. If this client certificate is stored on a separate physical device, such as a smart card, it constitutes a possession factor and therefore a second authentication factor (compared to your access keys, the knowledge factor, which acts as the first authentication factor).

  3. You can then activate a trusted session with your API access policy to simplify your API access.

Be careful when following this tutorial. Failing to properly configure your CA, client certificate, and API access rules can result in the locking of your account.

This tutorial contains the following steps:

Generate a CA

If you already have a CA in PEM format, you can skip this section.

  1. Generate a CA private key:

    $ openssl genrsa -aes256 -out ca-key.pem 4096

    It is recommended to protect your CA private key with a pass phrase.

  2. Using the CA private key, generate a CA certificate:

    $ openssl req -new \
        -x509 \
        -days 365 \
        -key ca-key.pem \
        -out ca-certificate.pem \
        -config <(cat /etc/ssl/openssl.cnf <(echo -e "[ext]\nbasicConstraints = critical,CA:TRUE,pathlen:1")) \
        -extensions ext
    • This command contains a specific "basic constraints" configuration which is necessary for the CA certificate to be accepted in the OUTSCALE Cloud.
    • This command makes the CA certificate valid for one year via the -days 365 parameter, but you can also specify a different value. For more information, see the official website of the OpenSSL command.

    Your CA private key is saved as ca-key.pem and your CA certificate as ca-certificate.pem.


Upload Your CA

Before you begin : Install OSC CLI. For more information, see Installing and Configuring OSC CLI.


  1. To upload your CA certificate using OSC CLI, your CA certificate must be formatted as a single-line string and must include quotes within the quoted string. You can upload your CA certificate directly in the correct format by using the following command:

    $ osc-cli api CreateCa \
        --Description "My company CA" \
        --CaPem "$(awk -v quote="'" 'BEGIN {printf quote} {ORS="\\n"} END {printf quote}; 1' ca-certificate.pem)"
    Response sample
    "Ca": {
    	"CaFingerprint": "FINGERPRINT",
        "CaId": "ca-12345678",
        "Description": "My company CA"
    }

    To verify that the CA was uploaded properly, you can compare the fingerprint of the above response with the fingerprint generated by this command:

    $ openssl x509 -in ca-certificate.pem -noout -sha1 -fingerprint

    Your CA certificate is now available for use in your OUTSCALE account.


Configure Your API Access Rules

  1. Create an API access rule to only allow API requests that provide a client certificate:

    $ osc-cli api CreateApiAccessRule \
        --CaIds '["ca-12345678"]' \
        --Description "Allow access with certificates validated by my CA"
  2. (Optional) Create an API access rule to only allow API requests originating from an IP that you have access to:

    $ osc-cli api CreateApiAccessRule \
        --IpRanges '["192.0.2.0/32"]' \
        --Description "Backup access if certificate access fails"

    If possible, use a different IP than the one you are currently using, such as a VPN IP, in order to properly test the access.

  3. List the IDs of all your API access rules:

    $ osc-cli api ReadApiAccessRules
    Response sample
        "ApiAccessRules": [
            {
                "ApiAccessRuleId": "aar-11111111",
                "CaIds": [],
                "Cns": [],
                "Description": "Allows all IPv4 domain",
                "IpRanges": [
                    "0.0.0.0/0"
                ]
            },
            {
                "ApiAccessRuleId": "aar-22222222",
                "CaIds": [],
                "Cns": [],
                "Description": "Allows Outscale Cockpit of this region",
                "IpRanges": [
                    "46.231.144.177/32"
                ]
            }
    		{
    			"ApiAccessRuleId": "aar-33333333",
    			"CaIds": [
    				"ca-12345678"
    			],
    			"Cns": [],
    			"Description": "Allow access with certificates validated by my CA", 
    			"IpRanges": []
    		}
    		{
    			"ApiAccessRuleId": "aar-44444444",
    			"CaIds": [],
    			"Cns": [],
    			"Description": "Backup access if certificate access fails",
    			"IpRanges": [
    				"192.0.2.0/32"
    			]
    		}
    	]

    By default, each account has the following API access rules:

    • Global access is allowed (0.0.0.0/0).
    • Access from the web interface Cockpit of the account Region is allowed.
  4. Delete the default API access rule that allows global access:

    $ osc-cli api DeleteApiAccessRule --ApiAccessRuleId "aar-11111111"


Test Your API Access

Generate a Client Certificate

For a proper multi-factor authentication, you can use a separate physical device, such as a smart card, to generate and store your client certificates.

  1. Generate a certificate private key and a certificate request:

    $ openssl req -new \
        -sha256 \
        -nodes \
        -newkey rsa:4096 \
        -keyout client-key.pem \
        -out client-certificate.csr

    Your certificate private key is saved as client-key.pem and your certificate request as client-certificate.csr.

  2. Using the above files, generate a client certificate signed by your CA:

    $ openssl x509 -req \
        -sha256 \
        -days 365 \
        -CAkey ca-key.pem \
        -CA ca-certificate.pem \
        -CAcreateserial \
        -in client-certificate.csr \
        -out client-certificate.pem \
        -extfile <(echo "extendedKeyUsage = clientAuth")

    This command makes the client certificate valid for one year via the -days 365 parameter, but you can also specify a different value. For more information, see the official website of the OpenSSL command.

    Your client certificate is saved as client-certificate.pem.

Test Your Client Certificate

  1. To configure OSC CLI to use your client certificate, add a profile (named for example secure) in your .osc_sdk/config.json file:

    .osc_sdk/config.json
    {
        "default": {
            "access_key": "ACCESSKEY",
            "secret_key": "SECRETKEY",
            "host": "outscale.com",
            "https": true,
            "method": "POST",
            "region_name": "eu-west-2"
        },
        "secure": {
            "access_key": "ACCESSKEY",
            "secret_key": "SECRETKEY",
            "host": "outscale.com",
            "https": true,
            "method": "POST",
            "region_name": "eu-west-2",
            "client_certificate": [
                "/PATHTO/client-certificate.pem",
                "/PATHTO/client-key.pem"
            ]
         }
    }

    Replace ACCESSKEY, SECRETKEY, eu-west-2, and /PATHTO/ with the adequate values.

  2. Test your secure profile by running any OSC CLI command:

    $ osc-cli api ReadVms --profile "secure"
    
  3. If your secure profile works properly, you can delete the default API access rule that allows access from Cockpit, as well as the API access rule that allows an IP you have access to:

    $ osc-cli api DeleteApiAccessRule --profile "secure" --ApiAccessRuleId "aar-22222222"
    $ osc-cli api DeleteApiAccessRule --profile "secure" --ApiAccessRuleId "aar-44444444"

    Your account is now configured to only allow API requests that provide a client certificate.

    If you can no longer access the APIs through the API access rules in place, you need to contact the Support team to regain access. For more information, see Technical Support.


Activate a Trusted Session

  1. Retrieve the IDs of all your access keys:

    $ osc-cli api ReadAccessKeys --profile "secure" 
    Response sample
    "AccessKeys": [
        {
            "AccessKeyId": "AAAAAAAAAAAAAAAA",
            "CreationDate": "YYYY-MM-DDThh:mm:ss.000Z",
            "LastModificationDate": "YYYY-MM-DDThh:mm:ss.000Z",
            "State": "ACTIVE"
        },
        {
            "AccessKeyId": "BBBBBBBBBBBBBBBB",
            "CreationDate": "YYYY-MM-DDThh:mm:ss.000Z",
            "LastModificationDate": "YYYY-MM-DDThh:mm:ss.000Z",
            "State": "ACTIVE"
        }
    ]
  2. Set expiration dates for all your access keys:

    $ osc-cli api UpdateAccessKey \
        --profile "secure" \
        --AccessKeyId "AAAAAAAAAAAAAAAA" \
        --State "ACTIVE" \
        --ExpirationDate "20XX-XX-XXTXX:XX:XXZ"
    
    $ osc-cli api UpdateAccessKey \
        --profile "secure" \
        --AccessKeyId "BBBBBBBBBBBBBBBB" \
        --State "ACTIVE" \
        --ExpirationDate "20XX-XX-XXTXX:XX:XXZ"

    All your access keys now have finite lifetimes.

  3. To activate a trusted session, modify your API access policy:

    $ osc-cli api UpdateApiAccessPolicy \
        --profile "secure" \
        --MaxAccessKeyExpirationSeconds XXXXXX \
        --RequireTrustedEnv True
    • The value of the MaxAccessKeyExpirationSeconds parameter must be greater than or equal to the remaining lifetime of each access key of your account.
    • Your access keys can expire before the end of the trusted session. Make sure you renew them as needed.
    • There can be a small delay between the response of the command and the effective application of the trusted session.

    Your trusted session is now activated. You no longer need to provide your client certificate until you deactivate the trusted session, except for specific actions. For more information, see About Your API Access Policy > Scope of a Trusted Session.