CA API Gateway 9.1

9.4 9.1

Working with the Generic Identity Management Service

The Generic Identity Management Service (GIMS) is an internal service that provides a standardized way of authenticating users and extracting authorization information (such as group membership) using the facilities provided by the gateway. The GIMS provides a set of APIs that can be consumed by an external application to authenticate a user against custom identity providers and retrieve authorization information.
gateway83
The Generic Identity Management Service (GIMS) is an internal service that provides a standardized way of authenticating users and extracting authorization information (such as group membership) using the facilities provided by the
CA API Gateway
. The GIMS provides a set of APIs that can be consumed by an external application to authenticate a user against custom identity providers and retrieve authorization information.
By default, the GIMS supports only authentication operations against the Internal Identity Provider. Support for other providers (such as LDAP or Federated) requires policy modifications.
 
The Generic Identity Management Service is configured as a service. At the policy level, you can authenticate users with the Authenticate Against Identity Provider Assertion or Authenticate User or Group Assertion.
 
Using the Generic Identity Management Service
To authenticate a user using the Generic Identity Management Service:
  1. Publish the GIMS in a policy using the Publish Internal Service Wizard. This is the internal service that performs user authentication against identity provider(s):
    /gims/
    <version>
    /authenticate
    where "<version>" is the version of the service deployed ("1" if the default routing URL is used)
  2. Modify the template policy to configure an identity provider.
    Tip:
     Search the policy for "Comment". The Add Comment to Policy assertion is used to provide placeholders in the places where the identity provider is defined.
  3. From the client side, call the service using the POST method to authenticate a user:
    POST /gims/
    <version>
    /authenticate
    The following table describes the parameters to be provided during authentication. These parameters are used by the default policy, but you can modify the default policy to meet your needs.
    Parameter
    Type
    Required
    Comment
    username
    string
    Yes
    login name of the user to be authenticated
    password
    string
    Yes
    user password credential
    format
    string
    No
    XML/JSON; default is XML
    The user account locks after 10 failed authentication attempts. The default lockup period is 1 hour, during which all authentication attempts fail, even with the correct credentials. The lockout counter resets after every successful authentication. The lockout does not affect Internal Identity Provider accounts accessed using the Policy Manager, it only affects the Generic Identity Management Service.
  4. After successful authentication, the
    CA API Gateway
     returns user authorization information in the format specified (XML/JSON).
Example of authorization info
Working_with_GIMS.png
The returned authorization information is defined as a list of attributes in XML or JSON form. The following table lists the standard attributes. Except for
dn
, all attributes are optional. Any additional attributes can be added for the specific client via policy.
 
Technical note:
 To view the XML schema that describes the GIMS authorization information response, download the gims.xsd.
Attribute
Type
Required
Comment
dn
string
yes
Distinguished name of the authenticated user. For some providers, this is the same as login; for others such as LDAP, it is a string containing a path to a specific folder where the resource is located.
login
string
no
Login name of the authenticated user
givenName
string
no
First name of the authenticated user
sn
string
no
Last name of the authenticated user
mail
string
no
Email address of the user
accountExpires
string
no
Date and time when account expires, in GMT. When it is set to "1969-12-31T23:59:59.999Z", the account never expires.
Error Conditions
The following table summarizes the errors returned by the
CA API Gateway
 when using the Generic Identity Management Service:
Condition
Error
Non-secure protocol is used
When the HTTP protocol is used, the Gateway returns HTTP code 500: "HTTP protocol is not supported. Use HTTPS instead"
Incorrect user credentials entered
The Gateway returns HTTP code: 401 "Authentication Required"
Required parameters are missing
The Gateway returns HTTP code 401: "Authentication Required"
Token parameter is present in the request
The Gateway returns HTTP code 401: "Authentication Required"
Incorrect provider name is present
The Gateway returns HTTP code 401: "Authentication Required"
Policy Error
The Gateway returns HTTP code 500: "Internal Server Error"

Content feedback and comments