Identify and authorize

Use the Identify and authorize policy to identify and validate the authorization of the applications to access the APIs.

On applying this policy, the applications are identified by using a set of identification types that are listed in the specifications table. The application is identified and authorized based on the application lookup condition.

The following application lookup conditions are supported:

  • Registered applications. Identifies the application and validates the identified application against the registered applications. On successful validation, it allows access to the API. The applications that are associated with the API are called as registered application.
  • Global applications. Identifies the application and validates the identified application against the global applications. On successful validation, it allows access to the API. All the active applications that are available are called as global application.

In IBM API Studio, this policy is identified by the kind IAM.

Example of an Identify and authorize policy in code view.

kind: IAM
apiVersion: api.ibm.com/v1
metadata:
  name: "sample-IAM"
  version: 1.0
  namespace: sample
spec:
  accessControl:
    - - httpBasic:
          applicationSecurity: 
            mode: authorize #possible values: identify, authenticate
          credentialLocation: #optional
            httpHeader:
              name: my-custom-header
          credentialRegistry: #Required
            - primary-ldap
            - secondary-ldap
          userGroupAuthorization: #optional
            requiredGroups:
              - admins
              - rnd
      - apiKey:
          applicationSecurity: #Required
            mode: authorize
          credentialLocation:
            httpHeader:
              name: my-api-key-header
    - - oauth:
          applicationSecurity:
            mode: authorize
          credentialLocation: #optional
            httpHeader:
              name: my-oauth-header
          providers: #required
            - provider1
            - provider2
          introspectionCredentials: 
            idHeader: my-id-header
            secretheader: my-secret-header
          audClaim: #optional 
            - aud1
            - aud2
          requiredScopes: 
            - provider: provider1
              scopes: 
                - read
                - write
            - provider: provider2
              scopes:
                - readwrite
    - - jwt:
          applicationSecurity:
            mode: authorize
          credentialLocation: #optional
            httpHeader:
              name: my-jwt-header
          providers:
            - provider1
            - provider2
          requiredClaims:
            - provider: provider1
              claims: #required 
                - name: my-claim-1
                  value: my-value1
                - name: my-claim-2
                  value: my-value2
    - - hostname:
          applicationSecurity: #Required
            mode: authorize
    - - ipAddress:
          applicationSecurity: #Required
            mode: authorize
    - - certificate:
          applicationSecurity: #Required
            mode: authorize
          credentialLocation:
            httpHeader:
              name: my-cert-header
    - - payloadElement: 
          name: 'payload_element_1'
    - - httpHeaders:
          applicationSecurity: #Required
            mode: authorize
          credentialLocation:
            - header1
            - header2
  extensions:
    dp-nano-gateway:
      apiVersion: api.ibm.com/v1
      spec:
        securityNamespace: sec1 #optional
        accessControl:
          payloadElement:
            - name: 'payload_element_1'
              applicationSecurity: #Required
                mode: authorize
              credentialLocation:
                regex: my-regex-*expr #or jsonata, only one allowed
    webm-gateway:
      apiVersion: api.ibm.com/v1
      spec:
        authenticationMode: 'ANY | ALL'
        allowAnonymous: {} 
        triggerPolicyViolation: true
        accessControl:
          kerberos:
            applicationSecurity: 
              mode: authorize 
            servicePrincipleName: ''
            servicePrinciplePassword: ''
          openIdConnect:
            applicationSecurity: 
              mode: authorize # authorize = registered; authenticate = global; identify = "global and default"
          payloadElement:
            applicationSecurity: #Required
              mode: authorize
            payLoadIdentifier:
              - jPath: '$.customer.name'
              - xpath: '$.customer.name'
                namespaces:
                  - prefix: ''
                    URI: ''
              - regex: '$.customer.name'

For the IAM policy kind, configure these specifications:

Property Description
spec
  • triggerPolicyViolation. Specifies whether to trigger a policy violation. When set to true in the code view, the policy triggers violation events for requests that do not include authorization headers.
  • httpBasic. Enables the use of authorization header in the request to identify and authorize the client application against the list of applications with the identifier username in IBM API Studio.
    Select one of the following options to specify where the client’s identity is verified:
    • Registered applications
    • Global applications
    • Global applications and default applications
  • apikey. Enables the use of the client's API key to validate the client's identity in the registered list of applications for the specified API.
    Select one of the following options to specify where the client’s identity is verified:
    • Registered applications
    • Global applications
    • Global applications and default applications
  • oauth. Enables the use of the OAuth2 token to identify the client, extract the access token from the HTTP request header, and verify the client's identity against the specified list of applications. By default, OAuth2 token is identified against the registered applications.
    Select one of the following options to specify where the client’s identity is verified:
    • Registered applications
    • Global applications
    • Global applications and default applications
  • jwt. Enables the use of the JSON Web Token (JWT) to identify the client, extract the claims from the JWT and validate the client's claims, and verify the client's identity against the specified list of application.
    Select one of the following options to specify where the client’s identity is verified:
    • Registered applications
    • Global applications
    • Global applications and default applications
  • hostName. Enables the use of host name address to identify the client, extract the client's hostname from the HTTP request header, and verify the client's identity in the specified list of applications in IBM API Studio.
    Select one of the following options to specify where the client’s identity is verified:
    • Registered applications
    • Global applications
    • Global applications and default applications
  • ipAddress. Enables the use of the IP address range to identify the client, extract the client's IP address from the HTTP request header, and verify the client's identity against the specified list of applications.
    Select one of the following options to specify where the client’s identity is verified:
    • Registered applications
    • Global applications
    • Global applications and default applications
  • certificate. Enables the use of the SSL certificate to identify the client, extract the client's identity certificate, and verify the client's identity (certificate-based authentication) against the specified list of applications.
    Select one of the following options to specify where the client’s identity is verified:
    • Registered applications
    • Global applications
    • Global applications and default applications
  • httpHeaders. Enables the use of any header in the request to identify and authorize the client application against the list of specified applications.
    Select one of the following options to specify where the client’s identity is verified:
    • Registered applications
    • Global applications
    • Global applications and default applications
  • kerberos. Enables the use of the Kerberos token to identify the client, extract the client's credentials from the Kerberos token, and verify the client's identity against the specified list of applications.
    Select one of the following options to specify where the client’s identity is verified:
    • Registered applications
    • Global applications
    • Global applications and default applications
  • openIdConnect. Enables the use of the OpenID (ID) token to identify the client, extract the client's credentials from the ID token, and verify the client's identity against the specified list of applications.
    Select one of the following options to specify where the client’s identity is verified:
    • Registered applications
    • Global applications
    • Global applications and default applications
  • payloadElement. Enables the use of the payload identifier to identify the client, extract the custom authentication credentials supplied in the request represented using the payload identifier, and verify the client's identity against the specified list of applications.
    Select one of the following options to specify where the client’s identity is verified:
    • Registered applications
    • Global applications
    • Global applications and default applications
  • payLoadIdentifier. Provide any of the payLoadIdentifier information:
    • jPath. Specifies the JSONPath for the payload identification. The format used in $.a.b. For example, $.name.id
    • xpath. Specifies the payload expression that the specified expression type in the request has to be converted to based on the following namespace values:
      • prefix. The namespace prefix of the payload expression to be validated
      • URI. The namespace URI of the payload expression to be validated
    • regex. Specifies the regular expression for the payload identification.