user-security

Use the user-security policy to extract a user's credentials, authenticate those credentials, and obtain authorization from the user.

Gateway support

Table 1. Table showing which gateways support this policy, and the corresponding policy version
Gateway Policy version
DataPower® API Gateway 2.0.0

This topic describes how to configure the policy in your OpenAPI source; for details on how to configure the policy in the assembly user interface, see User Security.

About

The user-security policy has the following format:
- user-security:
  version: version
  title: title
  description: description
  factor-id: factor ID
  extract-identity-method: method_used_to_extract_credentials
       .
       .
       .
     properties_specific_to_the specified_identity_extraction_method
       .
       .
       .
  user-auth-method: authentication_method
       .
       .
       .
     properties_specific_to_the specified_authentication_method
       .
       .
       .
  user-az-method: authorization_method
       .
       .
       .
     properties_specific_to_the specified_authorization_method
       .
       .
       .

Properties

Table 2. user-security policy properties
Property Required Description Data type
version Yes The policy version number string
title No The title of the policy. string
description No A description of the policy. string
factor-id No The identity that identifies the results of factor-authentication in the API context. string
extract-identity-method Yes Select the method that is used to extract the user credentials. The following options are available:
basic
Use basic authentication; no additional configuration is required.
context-var
The credentials are provided by API Connect context variables; specify the following properties:
  • user-context-var: the context variable that is used to obtain the user name.
  • pass-context-var: the context variable that is used to obtain the password.
html-form
Use forms based identity-extraction. You can use the default form or a custom form. To use the default form, specify ei-default-form: true. To use a custom form, specify ei-default-form: false and supply the following properties:
  • ei-custom-form: the location of the form.
  • ei-custom-form-tls-client-profile: the TLS client profile that is used to secure the connection to the remote server.

Use the ei-form-time-limit property to specify the time allowed to submit the form.

redirect
Use a redirect for identity-extraction; specify the following properties:
  • redirect-url: the URL fragment to which to redirect the request to obtain user credentials.
  • redirect-time-limit: the time allowed for the transaction to complete.
disabled
Identity-extraction is disabled; this aspect of processing is skipped.


Specify ei-stop-on-error: true to halt assembly processing in the event of identity-extraction failure. This field is required if identity extraction is not disabled.

 string
user-auth-method Yes Select the authentication method. The following options are available:
auth-url
The credentials are authenticated by an external endpoint; specify the following properties:
  • auth-url: the URL of the authentication endpoint.
  • auth-tls-client-profile: the TLS client profile that is used to secure the connection to the authentication endpoint.
  • auth-response-headers-pattern: the pattern that is used to select which response headers to add to the API context.
  • auth-response-header-credential: the response header that contains the authenticated user credentials.
ldap
The credentials are authenticated by an LDAP user registry; use the ldap-registry property to specify the required registry.
disabled
Authentication is disabled; this aspect of processing is skipped.


Specify au-stop-on-error: true to halt assembly processing in the event of user authentication failure. This field is required if authentication is not disabled.

 string
user-az-method Yes Select the authorization method. The following options are available:
authenticated
Implicitly accept any previously authenticated users; no additional configuration is required.
html-form
The user provides authorization through an HTML form. You can use the default form or a custom form.

To use the default form, specify az-default-form: true. To use a custom form, specify az-default-form: false.

Supply the following properties:
  • az-table-dynamic-entries: the name of a context variable that specifies the scopes that are to be added automatically to the authorization consent form.
  • az-form-time-limit: the time allowed to submit the form.
For a custom form, supply the following properties:
  • az-custom-form: the location of the form.
  • az-custom-form-tls-client-profile: the TLS client profile that is used to secure the connection to the remote server.
disabled
Authorization is disabled; this aspect of processing is skipped.


Specify az-stop-on-error: true to halt assembly processing in the event of user authorization failure. This field is required if authorization is not disabled.

 string

Example

# basic authentication with LDAP registry

- user-security:
    version: 2.0.0
    title: user-security
    factor-id: default
    extract-identity-method: basic
    ei-stop-on-error: true
    user-auth-method: ldap
    ldap-registry: corporate-ldap
    au-stop-on-error: true
    user-az-method: authenticated
    az-stop-on-error: true