Tutorial: Setting Up MFA for Your Account Using a Certificate

You can also set up multi-factor authentication (MFA) for Cockpit v2 using WebAuthn or an OTP. For more information, see Setting Up MFA for Your Account Using WebAuthn or an OTP.

To set up multi-factor authentication (MFA) on your OUTSCALE account using an x509 certificate:

You need to upload a Certificate Authority (CA) which will serve as the anchor for a chain of trust.
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).

Smart cards must follow the Personal Identity Verification (PIV) standard.
You can then activate a trusted session with your API access policy to simplify your API access. If you are using Cockpit v2, a trusted session is automatically simulated for you.

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 procedure uses OSC CLI only. Once MFA is set up for your OUTSCALE account, you can configure a client certificate for other interfaces such as Cockpit v2 or Terraform.

Generate a CA

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

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.

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.

Upload your CA certificate using OSC CLI:

$ osc-cli api CreateCa \
    --Description "My company CA" \
    --CaPem="$(cat 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 | awk '{gsub(/.*=/, ""); gsub(":",""); print tolower($0)}'

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

Configure Your API Access Rules

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"

(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.

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.

Delete the default API access rule that allows global access:

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

Generate a Client Certificate

For a stronger MFA, you can use a separate physical device, such as a smart card, to generate and store your client certificates.

Generate a certificate private key and a certificate request:
```
$ openssl req -new \
    -sha256 \
    -nodes \
    -newkey rsa:2048 \
    -keyout client-key.pem \
    -out client-certificate.csr
```
If you are using a separate physical device, adapt the newkey parameter value to your device specifications.

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

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.

Configure Your Access

Configuring Your Access for OSC CLI

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": "eu-west-2"
    },
    "secure": {
        "access_key": "ACCESSKEY",
        "secret_key": "SECRETKEY",
        "host": "outscale.com",
        "https": true,
        "method": "POST",
        "region": "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.

Test your secure profile by running any OSC CLI command:
```
$ osc-cli api ReadVms --profile "secure"
```

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 perform actions on your OUTSCALE account through the API access rules in place, you need to contact the Support team to regain access. For more information, see Technical Support.

Configuring Your Access for Cockpit v2

Convert your client certificate to the PKCS 12 format using the following command:

$ openssl pkcs12 \
    -inkey client-key.pem \
    -in client-certificate.pem \
    -export -out web-client-certificate.p12

Test your access by logging in to Cockpit v2. For more information, see Logging In and Out of a Trusted Session Using a Certificate.

If you are able to log in, 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, including requests sent by Cockpit v2.

Activate a Trusted Session

If your are using Cockpit v2, you do not need to activate a trusted session, as Cockpit v2 automatically simulates one for you.

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"
    }
]

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.

The access keys of EIM users cannot have expiration dates. If you are using EIM users in your account, you must delete their access keys. For more information, see Deleting an EIM Access Key.

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.

Related Pages

Corresponding API Methods

OUTSCALE API