Call the API / JWT

All the Cisco XDR Platform API calls use a JWT (JSON Web Token) as a means to authenticate users.

Here is an example of a decoded Cisco XDR Platform API JWT:

{
    "iss": "IROH Auth NAM",
    "sub": "idb-amp:13375ee9-2e3a-4e1b-977d-961facb5fd84",
    "exp": 1556693276,
    "nbf": 1556606576,
    "iat": 1556606876,
    "jti": "r93c7fa55-7a66-4708-824b-bd697d5d1211",
    "email": "dev.null@cisco.com",
    "https://schemas.cisco.com/iroh/identity/claims/version":
    "v1.20.0",
    "https://schemas.cisco.com/iroh/identity/claims/user/id":
    "idb-amp:13375ee9-2e3a-4e1b-977d-961facb5fd84",
    "https://schemas.cisco.com/iroh/identity/claims/user/email":
    "dev.null@cisco.com",
    "https://schemas.cisco.com/iroh/identity/claims/user/nick":
    "Dev Null",
    "https://schemas.cisco.com/iroh/identity/claims/user/idp/id":
    "idb-amp",
    "https://schemas.cisco.com/iroh/identity/claims/user/idp/org-id":
    "13375cf9-561c-4958-0000-6d84b7ef09d4",
    "https://schemas.cisco.com/iroh/identity/claims/user/idp/user-id":
    "13375ee9-2e3a-4e1b-977d-961facb5fd84",
    "https://schemas.cisco.com/iroh/identity/claims/org/id":
    "13375cf9-561c-4958-0000-6d84b7ef09d4",
    "https://schemas.cisco.com/iroh/identity/claims/org/name":
    "IROH Testing",
    "https://schemas.cisco.com/iroh/identity/claims/scopes":
    [ "iroh-admin",
      "integration",
      "private-intel",
      "admin",
      "profile",
      "inspect",
      "iroh-master",
      "iroh-auth",
      "sse",
      "users",
      "cisco",
      "casebook",
      "orbital",
      "enrich",
      "oauth",
      "global-intel",
      "account-activation",
      "collect",
      "response",
      "ui-settings" ],
    "https://schemas.cisco.com/iroh/identity/claims/oauth/client/id":
    "iroh-ui",
    "https://schemas.cisco.com/iroh/identity/claims/oauth/client/name":
    "iroh-ui",
    "https://schemas.cisco.com/iroh/identity/claims/oauth/kind":
    "session-token",
}

Standard JWT Claims

• iss: Issuer
  Issuer of the JWT. Should be equal to "IROH Auth".

See: https://tools.ietf.org/html/rfc7519#section-4.1.2

• sub: Subject
  The user identifier. All IROH (Incident Response Orchestration Hub) JWT must have this claim. This claim must be equal to the namespaced IROH “user/id” claims (user/id).

See: https://tools.ietf.org/html/rfc7519#section-4.1.2

• exp: Expiration Time
  The expiration time of the JWT.

See: https://tools.ietf.org/html/rfc7519#section-4.1.4

• nbf: Not Before
  The time before which the JWT is invalid. This field is useful to handle clock skew.

See: https://tools.ietf.org/html/rfc7519#section-4.1.5

• iat: Issued At
  The time the JWT was issued.

See: https://tools.ietf.org/html/rfc7519#section-4.1.6

• jti: JWT ID
  Unique identifier for this JWT.

See: https://tools.ietf.org/html/rfc7519#section-4.1.7

• email: email (optional)
  Standard field for Open Id Connect.

See: https://openid.net/specs/openid-connect-core-1_0.html#StandardClaims

Cisco XDR Platform API Specific JWT Claims

Those claims start with https://schemas.cisco.com/iroh/identity/claims/ to prevent any collision.

• version
  The JWT version. Cisco XDR APIs check the version is similar otherwise returns a 401.

• user/id
  The user’s unique identifier across IROH.

• user/email (optional)
  The user email, if known. This claim can be empty and is just informational. There is no email verification directly done by IROH.

• user/name (optional)
  The user name, if known. This claim can be empty and is just informational. IROH does not check the real user name of our users.

• user/nick (optional)
  The user nickname, if known. This claim can be empty and is just informational.

• org/id
  The organization unique identifier across IROH.

• org/name (optional)
  The organization name, if known. This claim can be empty and is just informational. IROH does not check the real org name of our users.

• scopes
  The list of scopes granted by the JWT. See Authorization Access / Scopes for more information about them.

• user/idp/id
  IROH uses 3rd party Identity Provider to authenticate users. More precisely IROH communicates with Cisco Security (AMP) or Threatgrid for getting the Identities.

• user/idp/org-id
  The org-id provided by the Identity Provider. It is generally not equal to the IROH org id.

• user/idp/user-id
  The user-id provided by the Identity Provider. It is generally not equal to the IROH user id.

• oauth/client/id
  The JWT is generally generated via an OAuth2 workflow. The OAuth2 client id involved in the JWT generation.

• oauth/client/name
  The JWT is generally generated via an OAuth2 workflow. This is the client name involved in the JWT generation.

• oauth/kind
  This can be either "session-token", "access-token" or "refresh-token".

• Session token are the one generated during a login workflow.

• Access token are the one generated during any OAuth2 workflow.

• Refresh token are reserved to refresh token generated during OAuth2 Auth Code Credential Grant.