API Authorization Schemes

Intersight supports the following API authorization schemes:

1. API keys with HTTP signature.
2. OAuth2 client credentials grant.
3. OAuth2 authorization code grant.
4. Session cookies, typically for browser-based sessions.

API Keys

An API key is used to authenticate and authorize API requests sent by a client using the HTTP signature scheme. API keys can be used by unattended, daemon clients that need to send requests to Intersight programmatically. API keys are based on public key cryptography. An API key is composed of a keyId and keySecret. The API client uses the API key to cryptographically sign each HTTP request sent to Intersight.

The "signature" parameter is a digital signature of the HTTP headers and body.

Benefits of using API Keys

API keys have the following benefits over user name and password:

• No shared secret is sent to Intersight, reducing the risk of compromising user credentials.
• A user can generate separate API keys for each client application.
• The API key allows you to monitor the application's API usage.
• The API usage and audit logs can be traced to individual client applications.
• When an API key is compromised, it can be revoked without affecting other client applications, and without compromising the user credentials (including cisco.com credentials)
• Each API key (hence each client application) can be assigned specific roles and privileges.

Generating API Keys

To obtain API keys for your API client, perform the steps below. Any user (Read-Only or Account Administrator) can generate API keys and can delete the keys that they generated. Account Administrators can delete the keys of the other users.

Generating an API key from the User Interface

1. Login to Intersight with your cisco.com credentials

2. From the Intersight dashboard, click your name in the upper right corner, then click "Generate API Keys"

3. You are presented with a key ID and private key.

   Note: This is your only opportunity to view, copy and download the private key. Intersight does not store the private key, and the private key cannot be recovered. However, you can create new API keys at any time.

4. Copy the key ID and private in a secure location. The client owns the private key and is responsible for maintaining the confidentiality of the private key. Secure storage of the private keys at the client side is beyond the scope of this document.

The generated private key and public key are encoded in PEM format.

Supported Cryptographic Algorithms

The following API key parameters are supported. For the detailed list of supported cryptographic parameters, see the Intersight OpenAPI documentation.

Hash Algorithm

The hash algorithm is used to compute the cryptographic digest of HTTP requests. The following algorithms are supported:

1. SHA-256 cryptographic hash, as defined by NIST in FIPS 180-4.
2. SHA-384 cryptographic hash, as defined by NIST in FIPS 180-4.
3. SHA-512 cryptographic hash, as defined by NIST in FIPS 180-4.
4. SHA-512/224 cryptographic hash, as defined by NIST in FIPS 180-4.
5. SHA-512/256 cryptographic hash, as defined by NIST in FIPS 180-4.

Key Generation Specification

The key generation specification is used to generate the private/public key pair. The following algorithms are supported:

1. RSA - The key pair is generated using the RSA algorithm and specified parameters. The supported RSA modulus values are 2048, 2560, 3072, 3584 and 4096.
2. EDDSA - The key pair is generated using Edwards-Curve Digital Signature Algorithm (EdDSA). The Edwards-curve Digital Signature Algorithm (EdDSA) is a variant of Schnorr's signature system with (possibly twisted) Edwards curves.
   1. Ed25519 - The edwards25519 curve, as defined in RFC 8032 section 5.1.
   2. Ed25519ph - The edwards25519 curve for the PureEdDSA variant.
   3. Ed25519ctx - The edwards25519 curve for the HashEdDSA variant.
3. ECDSA - The key pair is generated using Elliptic Curve Digital Signature Algorithm (ECDSA), as defined in FIPS 186-4. The ECDSA standard was originally developed for the American National Standards Institute by the Accredited Standards Committee on Financial Services, X9. ANSI X9.62 defines methods for digital signature generation and verification using ECDSA. Specifications for the generation of the domain parameters used during the generation and verification of digital signatures are also included in ANSI X9.62.
   1. P224 returns a Curve which implements P-224, as defined in FIPS 186-4, section D.2.2.
   2. P256 returns a Curve which implements P-256, as defined in FIPS 186-4, section D.2.3.
   3. P384 returns a Curve which implements P-384, as defined in FIPS 186-4, section D.2.4.
   4. P521 returns a Curve which implements P-521, as defined in FIPS 186-4, section D.2.5.

Signing Algorithm

1. RSASSA-PSS - RSA signature scheme specified in RFC 8017. It combines the RSASP1 and RSAVP1 primitives with the EMSA-PSS encoding method.
2. RSASSA-PKCS1-v1_5 - RSA signature scheme specified in RFC 8017. RSASSA-PKCS1-v1_5 is included only for compatibility with existing applications.
3. Ed25519 - The Ed25519 signature algorithm, as specified in RFC 8032. Ed25519 is a public-key signature system with several attractive features, including fast single-signature verification, very fast signing, fast key generation and high security level.
4. Ecdsa - The Elliptic Curve Digital Signature Standard (ECDSA), as defined by NIST in FIPS 186-4 and ANSI X9.62. The ECDSA signature is encoded in ASN.1 format as a sequence of the r and s values, as specified in RFC 3279.
5. Ecdsa P1363 - The Elliptic Curve Digital Signature Standard (ECDSA), as defined by NIST in FIPS 186-4 and ANSI X9.62. The ECDSA signature is encoded in the IEEE P.1363 format, as the raw concatenation of r and s values in their big endian representation.

Cryptographic Providers

The client must have a cryptographic provider which implements the cryptographic parameters specified in the API key. For example, if you use the PowerShell SDK to write the client, make sure the appropriate cryptographic providers are installed on the local system. If you create an RSA key pair with modulus set to 2048, the client must support 2048-bit private keys.

Authentication Process for API keys

When an API key is generated, the client can use the API key for authentication purposes to Intersight. The client application uses the key-id and the cryptographic private key to sign HTTP requests. Intersight verifies the signature of incoming HTTP requests by looking up the public key for the specified key-id.

Role-Based Access Control Policy and API Keys

The roles associated with the API key are inherited from the user who generated the API keys.

Audit Log and API Keys

To monitor the usage of API keys, the Intersight audit records includes the user name of the user who created the API keys; the session ID is set to the API key ID.

Deleting API keys

API keys can be deleted at any time. You can login to Intersight with Single Sign-on. From the Intersight dashboard, click your name in the upper right corner, then click "User Settings". Select the API key you want to delete.

HTTP Signature Algorithms

API keys are used to sign HTTP requests as follows:

1. A cryptographic digest of the body of the HTTP request is calculated using one of the supported cryptographic hash algorithms.
2. The value of the digest is base-64 encoded in the Digest HTTP header.
3. A signature is calculated as specified in the HTTP signature scheme, and the signature is added to the Authorization HTTP request header.

Session Cookies

Use of cookies is not recommended for daemonized, unattended API clients.

Cookies are used primarily by the Intersight HTML5 GUI client running in a browser. When accessing Intersight, end users must first login with Single Sign-on. When authentication is successful, the SAML identity provider sends a signed SAML assertion to Intersight, and Intersight generates a session cookie with a limited validity. The client must send the session cookie in each API request. The session cookie must be refreshed periodically before expiration.

TLS Security

This section describes security policies and best practices related to the use of Transport Layer Security (TLS) for Intersight API access.

When an API client establishes a secure connection to intersight.com, the server presents its notion of the service's identity in the form of a X.509 certificate that was issued by a Hydrant certification authority (CA). Since the communication occurs over the open Internet it is critical to follow best practices when verifying the authenticity of the server's identity.

Client-Side Verification of the TLS Connection

When an API client invokes the Intersight API, it must establish a secure communication over TLS. API clients are strongly recommended to follow best practices specified in RFC 6125.

At a high level, the client should verify the Intersight identity by performing the actions listed below each time it establishes a TLS connection to intersight.com:

1. Client sets "intersight.com" as the only acceptable identifier for the Intersight service.
2. Server provides its identifiers in the form of a PKIX certificate.
3. Client checks the "intersight.com" identifier against the server certificate for the purpose of finding an identifier match.
4. Client verifies the "intersight.com" certificate has been signed by the issuing Certificate Authority.

Server-Side Certificate Revocation Status

API clients should validate the status of the intersight.com certificate using at least one method supported by the issuing certificate authority. The CA supports two methods for checking the certificate status: a CRL distribution list and Online Certificate Status Protocol (OCSP).

Server-Side Certificate Renewal

The "intersight.com" X.509 certificate is generally valid for one year, and the certificate is renewed yearly before its expiration. As long as the API client is configured to trust the issuing Certificate Authority, the client will transparently handle yearly renewal of intersight.com certificates.

Client-Side Certificates

intersight.com does not support client-side certificates.

Supported TLS Protocol Versions and TLS Ciphers

The intersight.com service enforces a minimum required version of TLS. The list of supported TLS protocols and TLS ciphers may evolve over time, based on the discovery of security vulnerabilities in the TLS protocol or TLS ciphers.

Cross-Site Request Forgery (CSRF) Protection

Cross-Site Request Forgery (CSRF) is an attack that forces an end user to execute unwanted actions on a web application in which they're currently authenticated. SDK clients are not susceptible to CSRF attacks. This attack is applicable to API clients running in a browser. More information about CSRF is available at https://www.owasp.org/index.php/Cross-Site_Request_Forgery_(CSRF).

Resource Property Access Control

Intersight resources are described in the OpenAPI specification as a set of properties, similar to a JSON schema. API access to resource properties is controlled by an "access mode" meta-data attribute, as defined in the table below.

Protecting Secrets Embedded in API Resources

The Intersight API may define resources that contain secrets, such as API keys and credentials of managed endpoints. Secrets are encapsulated in resource properties that are protected with the following mechanisms:

• Property access mode specifies whether secrets should or should not be serialized in the HTTP response body
• Data-in-transit encryption, using TLS
• Data-at-rest encryption at the database layer and application layer.

Intersight Security Incident Response Policy

The Intersight operation team works with the Cisco Product Security Incident Response Team (PSIRT) to identify and remediate security issues. In some cases, changes to the security policies may have to be performed to remediate security issues or improve the security of Intersight. This includes but is not limited to vulnerabilities in the TLS protocol, TLS ciphers, and security issues related to CA certificates.

Webhooks Security

TLS Verification

Intersight verifies the TLS certificate of your payload URL when delivering Webhook payloads. TLS verification ensures secure delivery of Webhook payloads to your URL endpoint. Webhooks support only certificates signed by trusted root CAs. Self-signed certificates are not supported.

Webhooks Secret

Secret is used to sign HTTP requests using the HTTP signature scheme. See HTTP Signature Algorithms section. Webhook server is responsible for the signature verification to prevent forged requests attacks.