Advanced Access Control Configuration

This configuration module is used to apply configuration to the runtime Liberty server. This includes configuring the runtime authorization server, context-based access, SCIM, FIDO2, Authentication, Context-Based Access and MMFA.

Example

access_control:
   authentication:
      policies:
      - name: "Username Password"
         description: "Username and password authentication policy."
         enabled: true
         uri: "urn:ibm:security:authentication:asf:password"
         policy: "<Policy xmlns=\"urn:ibm:security:authentication:policy:1.0:schema\" PolicyId=\"urn:ibm:security:authentication:asf:password\"><Description>Username and password authentication policy.</Description><Step type=\"Authenticator\"><Authenticator AuthenticatorId=\"urn:ibm:security:authentication:asf:mechanism:password\"/></Step><Actions><Action On=\"null\" type=\"null\"><AttributeAssignments/></Action></Actions></Policy>"
      mechanisms:
      - name: "Username Password"
        type: "Username Password"
        description: "Username password authentication"
        uri: "urn:ibm:security:authentication:asf:mechanism:password"
        properties:
        - usernamePasswordAuthentication.enableLastLogin: "false"
        - usernamePasswordAuthentication.loginFailuresPersistent: "false"
        - usernamePasswordAuthentication.maxServerConnections: "16"
        - usernamePasswordAuthentication.mgmtDomain: "Default"
        - usernamePasswordAuthentication.sslServerStartTLS: "false"
        - usernamePasswordAuthentication.useFederatedDirectoriesConfig: "false"
        - usernamePasswordAuthentication.userSearchFilter: "(|(objectclass=ePerson)(objectclass=Person))"
        - usernamePasswordAuthentication.ldapBindDN: "cn=root,secAuthority=Default"
        - usernamePasswordAuthentication.ldapHostName: "openldap"
        - usernamePasswordAuthentication.ldapBindPwd: "Passw0rd"
        - usernamePasswordAuthentication.ldapPort: "636"
        - usernamePasswordAuthentication.sslEnabled: "true"
        - usernamePasswordAuthentication.sslTrustStore: "lmi_trust_store"
        attributes:
        - selector: "mobile"
          name: "mobileNumber"
          namespace: "urn:ibm:security:authentication:asf:mechanism:password"
        - selector: "mail"
          name: "emailAddress"
          namespace: "urn:ibm:security:authentication:asf:mechanism:password"

API Protection

OIDC API protection configuration for definitions and clients. This is capable of creating OpenBanking and FAPI compliant defintions and clients.

class src.ibmvia_autoconf.access_control.AAC_Configurator.API_Protection

Example:

api_protection:
  definitions:
  - name: "Verify Demo - Open Banking"
    description: "The Open Banking Definition."
    tcm_behavior: "NEVER_PROMPT"
    multiple_refresh_tokens: true
    access_policy: "Open_Banking"
    oidc:
      poc: "https://my.ibmsec.idp.com"
      iss: "https://my.ibmsec.idp.com"
      lifetime: 20
      enabled: true
      keystore: "rt_profile_keys"
      cert: "server"
      alg: "RS256"
    pre_token_mapping_rule: "Verify Demo - Open Banking_pre_token_generation.js"
    post_token_mapping_rule: "Verify Demo - Open Banking_post_token_generation.js"
  - name: "Verify Demo - Client Credentials Authorization Code Consent PSD2"
    description: "For Fintechs, this is Client Credentials and Authorization Code with consent."
    grant_types:
      - "AUTHORIZATION_CODE"
      - "CLIENT_CREDENTIALS"
    max_authorization_grant_lifetime: 7200
  - name: "Verify Demo - Client Credentials AaaS"
    description: "This is for the AaaS mock server access."
    tcm_behavior: "NEVER_PROMPT"
    grant_types:
      - "CLIENT_CREDENTIALS"
    access_token_lifetime: 999999999
  clients:
  - name: "J.P. Norvill"
    client_id: "ob_client"
    client_secret: "hunter2"
    redirect_uri:
      - "https://jpnorvill.com/auth"
      - "http://my.ibmsec.spa.com:19080/auth"
    company_name: "JPNorvill"
    contact_type: "TECHNICAL"
    definition: "Verify Demo - Open Banking"

class Client

client_id: str | None: A unique OAUTH client identifier to identify this client to the authorization server. It is sent in the token endpoint request to perform client authentication. If omitted, a random and unique alphanumeric string is generated and used as the client identifier.

client_secret: str | None: A string that identifies this client as confidential and serves as this client’s secret. The client secret mechanism is a means of authorizing a client. Applications requesting an access token must know the client secret in order to gain the token. If omitted, the value is set to null and the client is considered a public client.

comapny_url: str | None: URL for the company associated with this client. If omitted, the value is set to null.

company_name: str | None: Name of the company associated with this client.

contact_person: str | None: Name of the contact person for this client. If omitted, the value is set to null.

contact_type: str | None: Further describes the contact. Valid values are TECHNICAL, SUPPORT, ADMINISTRATIVE, BILLING, or OTHER. If omitted, the value is set to null.

defintition: str: The name of the related API protection definition which owns and defines this client. A client registration can only belong to one definition, but a definition can own many client registrations. The definition cannot be modified.

email: str | None: The email address of the contact person for this client. If omitted, the value is set to null.

encryption_cert: str | None: The certificate label of the JWT encryption key. Not required for dir/AES key wrap / AES GCM key wrap.

encryption_db: str | None: The database containing the JWT encryption key. Not required for dir/AES key wrap / AES GCM key wrap.

ext_properties: dict | None: Dynamic Client information. This is free form JSON.

introspect_with_secret: bool | None: Does this client require a client secret when introspecting. When not provided defaults to true.

jwks_uri: str | None: URI which is the location that a clients published JWK set. Used in validating client assertions, request JWTs and for encrypting id_tokens.

name: str: A meaningful name to identify this API protection client.

other_info: str | None: Other information about the client contact. If omitted, the value is set to null.

phone: str | None: The telephone number of the contact person for this client. Input must be completely numeric with no parenthesis or dashes. If omitted, value is set to null.

redirect_uri: str | None: The redirect URI to use for this client. If omitted, the value is set to null.

require_pkce: bool | None: Whether or not this client must perform proof of key exchange when performing an authorization code flow. This follows RFC 7636. Defaults to false.

class Definition

class Attribute_Source

name: str: Name the attribute should be exposed as.

source: str: Reference to the attribute source which should be used to retrieve the value.

class OIDC

class OIDC_Encoding

alg: str: The key agreement algorithm for encryption. See LMI for choices. Default value is RSA-OAEP-256.

enabled: bool: Is encryption enabled for this definition.

enc: str: The encryption algorithm. Default value is A128CBC-HS256.

alg: str: The signing algorithm for the JWT, valid values include combinations of HS/ES/RS and 256/384/512, eg RS256. If HS* signing is used, clients MUST have a client secret to form JWTs. Default value is RS256

cert: str: The certificate label of the signing key for RS/ES signing methods.

db: str: The database containing the signing key for RS/ES signing methods.

dynamic_clients: bool: Whether or not the client registration endpoint will be enabled for this definition. If not presented in an update or create then a value of false will be used.

enc: OIDC_Encoding: JWT encryption config.

fapi_compliant: bool: Whether or not the definition should be strictly FAPI Compliant. Setting this to true will automatically set OIDC Compliant to true.

iss: str: The issuer identifier of this definition. Should have the prefix https://.

issue_secret: bool: Whether or not a client secret will be issued to dynamic clients. When this is set to true, a client secret will only be issued to a client registration request which is made by an authenticated user. If not presented in an update or create then a value of false will be used.

lifetime: int: The lifetime of the id_tokens issued

oidc_compliant: bool: Whether or not the definition should be strictly OIDC Compliant.

poc: str: The Point of Contact URL for this definition, must be a valid URL. Should include the junction portion.

access_policy: str | None: The name of access policy assigned to this definition.

access_token_length: int | None: Length (characters) of an access token. Maximum value is 500 characters. If not provided, the access token length is set to 20 characters.

access_token_lifetime: int | None: Validity of the access token, in seconds. When this lifetime expires, the client cannot use the current access token to access the protected resource. If not provided, the access token lifetime is set to 3600 seconds.

attribute_sources: List[Attribute_Source] | None: Array of configured attribute sources to use in id_token generation and userinfo requests.

authorization_code_length: int | None: Length of an authorization code. This field is required if grant_types includes AUTHORIZATION_CODE. Maximum value is 500 characters. If not provided, the authorization code length is set to 30 characters.

authorization_code_lifetime: int | None: Validity period, in seconds, of the authorization code. This field is required if grant_types includes AUTHORIZATION_CODE. If not provided, the authorization code lifetime is set to 300 seconds.

description: str | None: An optional description of the API protection definition.

enforce_single_use_grant: bool | None: True if all tokens of the authorization grant should be revoked after an access token is validated. If not provided, the single-use authorization grant is not enforced (false).

grant_types: List[str]: A list of supported authorization grant types. Valid values are AUTHORIZATION_CODE, RESOURCE_OWNER_PASSWORD_CREDENTIALS, CLIENT_CREDENTIALS, IMPLICIT_GRANT, SAML_BEARER, JWT_BEARER, and DEVICE. At least one must be specified.

issue_refresh_token: int | None: True if a refresh token should be issued to the client. This option is only applicable when grant_types includes AUTHORIZATION_CODE or RESOURCE_OWNER_PASSWORD_CREDENTIALS. Otherwise, include this field with a value of false. If not provided, it is set to true.

max_authorization_grant_lifetime: int | None: The maximum duration of a grant, in seconds, where the resource owner authorized the client to access the protected resource. The maximum value is 604800 seconds; the minimum is 1. The value for this lifetime must be greater than the values specified for the authorization code and access token lifetimes. If not provided, the value is set to 604800.

multiple_refresh_tokens: bool | None: True if multiple refresh tokens are stored so that the old refresh token is valid until the new refresh token is successfully delivered. Applicable if issue_refresh_token is true. Otherwise, include this field with a value of false. If not provided, the default value is false.

name: str: A unique name for the API protection definition.

oidc: OIDC | None: The OIDC configuration for this API protection definition.

pin_length: int | None: The length of a PIN. Applicable when pin_policy is true. Maximum value is 12 characters. Minimum value is 3 characters. If not provided, the PIN length is set to 4 characters.

pin_policy: bool | None: True if the refresh token will be further protected with a PIN provided by the API protection client. Applicable when issue_refresh_token is true. Otherwise, include this field with a value of false. If not provided, the PIN policy is disabled (false).

post_token_mapping_rule: str | None: Path to file to upload as JavaScript post-token rule.

pre_token_mapping_rule: str | None: Path to file to upload as JavaScript pre-token rule.

refresh_token_length: int | None: Length of a refresh token. Maximum value is 500 characters.If not provided, the refresh token length is set to 40 characters.

single_token_per_grant: bool | None: True if previously granted access tokens should be revoked after a new access token is generated by presenting the refresh token to the authorization server. Applicable if issue_refresh_token is true. Otherwise, include this field with a value of false. If not provided, the single access token per authorization grant is enforced (true).

tcm_behavior: str: Identifies the Trusted Client Manager behavior concerning trusted clients and consent. Specify ALWAYS_PROMPT to always prompt the user to provide their consent for a new authorization grant. Specify NEVER_PROMPT to allow implicit consent whereby the user is never shown a consent to authorize prompt. Specify PROMPT_ONCE_AND_REMEMBER to have the user prompted for consent to authorize when a previous consent for the client with the particular scope is not already stored and to have the Trusted Client Manager store the consent decision when consent is granted so it can be referred to during the next access attempt.

token_char_set: str | None: String of characters that can be used to generate tokens. If not provided, the value will be set to alphanumeric character set, 0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz. The maximum number of token characters that can be specified is 200.

clients: List[Client] | None: List of OIDC clients to create.

definitions: List[Definition] | None: List of OIDC defintions to create.

Attribute Sources

To set Attribute sources, see the entry in the Appliance or Container documentation.

Authentication

This section describes how to create authentication policies and mechanisms. Authentication policies can be used in risk-based access or context-based access policies to conditionally enforce additional authentication/authorization requirements.

class src.ibmvia_autoconf.access_control.AAC_Configurator.Authentication

Example:

authentication:
  mechanisms:
  - name: "Verify Demo - QR Code Initiate"
    uri: "urn:ibm:security:authentication:asf:mechanism:qr_code_initiate"
    description: "InfoMap to initiate the QR login"
    type: "InfoMapAuthenticationName"
    properties:
    - mapping_rule: "InfoMap_QRInitiate"
    - template_file: ""
  - name: "Verify Demo - QR Code Response"
    uri: "urn:ibm:security:authentication:asf:mechanism:qr_code_response"
    description: "InfoMap to use the LSI for QR login"
    type: "InfoMapAuthenticationName"
    properties:
    - mapping_rule: "InfoMap_QRResponse"
    - template_file: ""
  - name: "Username Password"
    uri: "urn:ibm:security:authentication:asf:mechanism:password"
    description: "Username password authentication"
    type: "Username Password"
    properties:
      usernamePasswordAuthentication.ldapHostName: "openldap"
      usernamePasswordAuthentication.loginFailuresPersistent: "false"
      usernamePasswordAuthentication.ldapBindDN: !secret default/isva-secrets:ldap_bind_dn
      usernamePasswordAuthentication.maxServerConnections: "16"
      usernamePasswordAuthentication.mgmtDomain: "Default"
      usernamePasswordAuthentication.sslEnabled: "true"
      usernamePasswordAuthentication.ldapPort: "636"
      usernamePasswordAuthentication.sslTrustStore: "lmi_trust_store"
      usernamePasswordAuthentication.userSearchFilter: "usernamePasswordAuthentication.userSearchFilter"
      usernamePasswordAuthentication.ldapBindPwd: !secret default/isva-secrets:ldap_bind_pwd
      usernamePasswordAuthentication.useFederatedDirectoriesConfig: "false"
  - name: "TOTP One-time Password"
    uri: "urn:ibm:security:authentication:asf:mechanism:totp"
    description: "Time-based one-time password authentication"
    type: "TOTP One-time Password"
    properties:
      otp.totp.length: "6"
      otp.totp.macAlgorithm: "HmacSHA1"
      otp.totp.oneTimeUseEnabled: "true"
      otp.totp.secretKeyAttributeName: "otp.hmac.totp.secret.key"
      otp.totp.secretKeyAttributeNamespace: "urn:ibm:security:otp:hmac"
      otp.totp.secretKeyUrl: "otpauth://totp/Example:@USER_NAME@?secret=@SECRET_KEY@&issuer=Example"
      otp.totp.secretKeyLength: "32"
      otp.totp.timeStepSize: "30"
      otp.totp.timeStepSkew: "10"
  - name: "reCAPTCHA Verification"
    uri: "urn:ibm:security:authentication:asf:mechanism:recaptcha"
    description: "Human user verification using reCAPTCHA Version 2.0."
    type: "ReCAPTCHAAuthenticationName"
    properties:
      reCAPTCHA.HTMLPage: "/authsvc/authenticator/recaptcha/standalone.html"
      reCAPTCHA.apiKey: !secret default/isva-secrets:recaptcha_key
  - name: "End-User License Agreement"
    uri: "urn:ibm:security:authentication:asf:mechanism:eula"
    description: "End-user license agreement authentication"
    type: "End-User License Agreement"
    properties:
      eulaAuthentication.acceptIfLastAcceptedBefore: "true"
      eulaAuthentication.alwaysShowLicense: "false"
      eulaAuthentication.licenseFile: "/authsvc/authenticator/eula/license.txt"
    - eulaAuthentication.licenseRenewalTerm: "0"
  - name: "FIDO Universal 2nd Factor"
    uri: "urn:ibm:security:authentication:asf:mechanism:u2f"
    description: "FIDO Universal 2nd Factor Token Registration and Authentication"
    type: "U2FName"
    properties:
      U2F.attestationSource: ""
      U2F.attestationType: "None"
      U2F.appId: "www.myidp.ibm.com"
      U2F.attestationEnforcement: "Optional"
  policies:
  - name: "Verify Demo - Initiate Generic Message Demo Policy"
    uri: "urn:ibm:security:authentication:asf:verify_generic_message"
    description: "IBM MFA generic message policy."
    policy: "<Policy xmlns="urn:ibm:security:authentication:policy:1.0:schema" PolicyId="urn:ibm:security:authentication:asf:verify_generic_message"><Description>IBM MFA generic message policy.</Description><Step id="id15342210896710" type="Authenticator"><Authenticator id="id15342210896711" AuthenticatorId="urn:ibm:security:authentication:asf:mechanism:generic_message"/></Step><Step id="id15342211135160" type="Authenticator"><Authenticator id="id15342211135161" AuthenticatorId="urn:ibm:security:authentication:asf:mechanism:mmfa"><Parameters><AttributeAssignment AttributeId="contextMessage"><AttributeDesignator AttributeId="message" Namespace="urn:ibm:security:asf:response:token:attributes" Source="urn:ibm:security:asf:scope:session" DataType="String"/></AttributeAssignment><AttributeAssignment AttributeId="mode"><AttributeValue DataType="String">Initiate</AttributeValue></AttributeAssignment><AttributeAssignment AttributeId="policyURI"><AttributeValue DataType="URI">urn:ibm:security:authentication:asf:verify_mmfa_response_fingerprint</AttributeValue></AttributeAssignment><AttributeAssignment AttributeId="username"><AttributeDesignator AttributeId="username" Namespace="urn:ibm:security:asf:response:token:attributes" Source="urn:ibm:security:asf:scope:session" DataType="String"/></AttributeAssignment></Parameters></Authenticator></Step></Policy>"
  - name: "Verify Demo - QR Code Initiate"
    uri: "urn:ibm:security:authentication:asf:qrlogin_initiate"
    description: "Login without a password - use your phone and scan a QR code!"
    policy: "<Policy xmlns="urn:ibm:security:authentication:policy:1.0:schema" PolicyId="urn:ibm:security:authentication:asf:qrlogin_initiate"><Description>Login without a password - use your phone and scan a QR code!</Description><Step id="id15033758674560" type="Authenticator"><Authenticator id="id15033758674561" AuthenticatorId="urn:ibm:security:authentication:asf:mechanism:qr_code_initiate"/></Step></Policy>",
  - name: "Verify Demo - QR Code Response"
    uri: "urn:ibm:security:authentication:asf:qrlogin_response"
    description: "Login without a password - use your phone and scan a QR code!"
    policy: "<Policy xmlns="urn:ibm:security:authentication:policy:1.0:schema" PolicyId="urn:ibm:security:authentication:asf:qrlogin_response"><Description>qrlogin_response<\/Description><Step id="id15033758436320" type="Authenticator"><Authenticator id="id15033758436321" AuthenticatorId="urn:ibm:security:authentication:asf:mechanism:qr_code_response"\/><\/Step><\/Policy>"
  - name: "FIDO U2F Authenticate"
    uri: "urn:ibm:security:authentication:asf:u2f_authenticate"
    description: "FIDO Universal 2nd Factor Token Authentication"
    policy: "<Policy xmlns="urn:ibm:security:authentication:policy:1.0:schema" PolicyId="urn:ibm:security:authentication:asf:u2f_authenticate"><Description>FIDO Universal 2nd Factor Token Authentication</Description><Step id="Step_1" type="Authenticator"><Authenticator id="Auth_1" AuthenticatorId="urn:ibm:security:authentication:asf:mechanism:u2f"><Parameters><AttributeAssignment AttributeId="mode"><AttributeValue DataType="String">Authenticate</AttributeValue></AttributeAssignment><AttributeAssignment AttributeId="username"><AttributeDesignator AttributeId="username" Namespace="urn:ibm:security:asf:request:parameter" Source="urn:ibm:security:asf:scope:request" DataType="String"/></AttributeAssignment></Parameters></Authenticator></Step><Actions><Action On="null" type="null"><AttributeAssignments/></Action></Actions></Policy>"

class Mechanism

class Attribute

name: str: Authentication service context attribute.

namespace: str: Authentication service namespace of name.

selector: str: Name of a registry attribute to obtain.

attributes: List[Attribute] | None: List of attribute to add from the request context.

description: str | None: An optional description of the authentication mechanism.

name: str: A unique name for the authentication mechanism.

properties: dict: List of properties to configure for mechanism. The property names are different for rach of the mechanism types.

type: str

‘HOTP One-time Password’, ‘MAC One-time Password’, ‘RSA One-time Password’, ‘TOTP One-time Password’, ‘Consent to device registration’, ‘One-time Password’, ‘HTTP Redirect’, ‘Username Password’, ‘End-User License Agreement’, ‘Knowledge Questions’, ‘Mobile User Approval’, ‘reCAPTCHA Verification’, ‘Info Map Authentication’, ‘Email Message’, ‘MMFA Authenticator’, ‘SCIM Config’, ‘FIDO Universal 2nd Factor’, ‘Cloud Identity JavaScript’, ‘QRCode Authenticator’, ‘FIDO2 WebAuthn Authenticator’, ‘Decision JavaScript’, ‘RSA SecurID’, ‘FIDO2 WebAuthn Registration’ and ‘OTP Enrollment’

Type:: Type of mechanism to create. Valid types include

uri: str: The unique resource identifier of the authentication mechanism.

class Policy

description: str: Description of the authentication policy.

dialect: str | None: Authentication policy specification used to format the authentication policy. The only valid value is urn:ibm:security:authentication:policy:1.0:schema.

enabled: bool: True if the policy is enabled and invocable at runtime. Set to false to disable the policy. If the policy is disabled it cannot be used by context based access.

name: str: Specify a unique name for the authentication policy.

policy: str: Configured policy content that uses the specified authentication policy dialect.

uri: str: Specify a unique resource identifier for the authentication policy.

mechanisms: List[Mechanism] | None: List of authentication mechanism to create or update.

policies: List[Policy] | None: List of authentication policies to create or update.

Context Based Access Control

This section covers the configuration of the Context Based Access policy engine of a Verify Identity Access deployment. Context based access policies are capable of defining conditional authentication requirements based on administrator defined requirements (such as device registration status, ip reputation, authentication method enrollment for a user).

class src.ibmvia_autoconf.access_control.AAC_Configurator.Access_Control

Example:

access_control:
  risk_profiles:
  - name: "myLocation"
    active: true
    attributes:
    - weight: 50
        id: "28"
    - weight: 10
        name: "geoCountryCode"
    - weight: 10
        name: "geoRegionCode"
    - weight: 10
        name: "geoCity"
    predefined: false
  policies:
  - name: "Verify Demo - MFA Login Policy"
    policy: "<?xml version="1.0" encoding="UTF-8"?><!-- PolicyTag=urn:ibm:security:isam:8.0:xacml:2.0:config-policy --><!-- PolicyName='Verify Demo - MFA Login Policy' --><PolicySet xmlns="urn:oasis:names:tc:xacml:2.0:policy:schema:os" xmlns:xacml-context="urn:oasis:names:tc:xacml:2.0:context:schema:os" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="urn:oasis:names:tc:xacml:2.0:policy:schema:os http://docs.oasis-open.org/xacml/access_control-xacml-2.0-policy-schema-os.xsd" PolicySetId="urn:ibm:security:config-policy" PolicyCombiningAlgId="urn:oasis:names:tc:xacml:1.0:policy-combining-algorithm:deny-overrides"><Description>Example CBA Policy for the MFA Banking Demo password-less login</Description><Target/><Policy PolicyId="urn:ibm:security:rule-container:0" RuleCombiningAlgId="urn:oasis:names:tc:xacml:1.0:rule-combining-algorithm:first-applicable"><Target/><Rule RuleId="urn:ibm:security:rule:0" Effect="Permit"></Rule><Obligations><Obligation ObligationId="urn:ibm:security:authentication:asf:verify_mmfa_request_fingerprint" FulfillOn="Permit"/></Obligations></Policy></PolicySet>"
  - name: "Verify Demo - EULA"
    policy: "<?xml version="1.0" encoding="UTF-8"?><!-- PolicyTag=urn:ibm:security:isam:8.0:xacml:2.0:config-policy --><!-- PolicyName='Verify Demo - EULA' --><PolicySet xmlns="urn:oasis:names:tc:xacml:2.0:policy:schema:os" xmlns:xacml-context="urn:oasis:names:tc:xacml:2.0:context:schema:os" xmlns:xsi="http:\/\/www.w3.org\/2001\/XMLSchema-instance" xsi:schemaLocation="urn:oasis:names:tc:xacml:2.0:policy:schema:os http:\/\/docs.oasis-open.org\/xacml\/access_control-xacml-2.0-policy-schema-os.xsd" PolicySetId="urn:ibm:security:config-policy" PolicyCombiningAlgId="urn:oasis:names:tc:xacml:1.0:policy-combining-algorithm:first-applicable"><Description>GDPR Compliance (Acceptance of ToS)<\/Description><Target\/><Policy PolicyId="urn:ibm:security:rule-container:0" RuleCombiningAlgId="urn:oasis:names:tc:xacml:1.0:rule-combining-algorithm:first-applicable"><Target\/><Rule RuleId="urn:ibm:security:rule:0" Effect="Permit"><Condition><Apply FunctionId="urn:oasis:names:tc:xacml:1.0:function:and"><Apply FunctionId="urn:oasis:names:tc:xacml:1.0:function:string-at-least-one-member-of"><Apply FunctionId="urn:oasis:names:tc:xacml:1.0:function:string-bag"><AttributeValue DataType="http:\/\/www.w3.org\/2001\/XMLSchema#string">urn:ibm:security:authentication:asf:mechanism:eula<\/AttributeValue><\/Apply><SubjectAttributeDesignator AttributeId="urn:ibm:security:subject:authenticationMechanismTypes" DataType="http:\/\/www.w3.org\/2001\/XMLSchema#string" MustBePresent="false"\/><\/Apply><\/Apply><\/Condition><\/Rule><\/Policy><Policy PolicyId="urn:ibm:security:rule-container:1" RuleCombiningAlgId="urn:oasis:names:tc:xacml:1.0:rule-combining-algorithm:first-applicable"><Target\/><Rule RuleId="urn:ibm:security:rule:1" Effect="Permit"><\/Rule><Obligations><Obligation ObligationId="urn:ibm:security:authentication:asf:eula" FulfillOn="Permit"\/><\/Obligations><\/Policy><\/PolicySet>"
    description: "GDPR Compliance (Acceptance of ToS)"
  resources:
  - server: "my.ibmsec.idp"
    resource_uri: "/login"
    policies:
    - name: "Verify Demo - MFA Login Policy"
      type: "policy"
  - server: "my.ibmsec.idp"
    resource_uri: "/protected/transfer"
    policies:
    - name: "Verify Demo - MFA Transaction Policy"
      type: "policy"
  - server: "my.ibmsec.idp"
    resource_uri: "/isam/sps/SP-SAML-QC/saml20/login"
    policies:
    - name: "Verify Demo - MFA Office 365 Login"
      type: "policy"

class Policy

attributes_required: bool: If true all the policy attributes must be present in the request for the policy to be evaluated.

description: str | None: An optional description of the policy.

dialect: str | None: The XACML specification used within the policy. Only valid value is XACML Version 2, urn:oasis:names:tc:xacml:2.0:policy:schema:os.

name: str: The name of the policy.

policy: str: The configured policy in XACML 2.0.

class Resource

class Policy_Attachment

name: str: Name of the policy, policy set, or API protection definition.

type: str: The type of attachment. Values include policy, policyset, or definition.

cache: int: 0 to disable the cache for this resource, -1 to cache the decision for the lifetime of the session or any number greater than 1 to set a specific timeout (in seconds) for the cached decision. If not specified a default of 0 will be used.

policies: List[Policy_Attachment]: Array of attachments (policy, policy sets, and API protection definitions) that define the access protection for this resource.

policy_combining_algorithm: str | None: permitOverrides to allow access to the resource if any of the attachments return permit; denyOverrides to deny access to the resource if any of the attachments return deny. Default is denyOverrides.

resource_uri: str: The resource URI of the resource in the protected object space.

server: str: The web container that contains the protected object space for a server instance.

class Risk_Profiles

class Attribute

id: str | None: Internally assigned ID value of the attribute. The attribute must have a type field value of true for risk. Either the name or id of the attribute must be defined.

name: str | None: Name of the attribute. The attribute must have a type field value of true for risk. Either the name or id of the attribute must be defined.

weight: int: Determines the importance of this attribute within the associated risk profile. A higher weight value indicates the attribute has more importance within the risk profile. The weight values of the attributes are used in determining the risk score or the level of risk associated with permitting a request to access a resource.

active: bool: True indicates this risk profile is the currently active risk profile. Only one profile can be active at a time.

attributes: List[Attribute] | None: Array of attributes comprising this risk profile and the weight value of each attribute which is used in determining the risk score.

description: str | None: An optional brief description of the risk profile.

name: str: A unique name for the risk profile.

predefined: bool | None: False to indicate this risk profile is custom defined.

policies: List[Policy] | None: List of Risk Based Access policies to create.

resources: List[Resource] | None: List of resources to be created and corresponding policies which should be attached to each resource.

risk_profiles: List[Risk_Profiles] | None: List of Risk Profiles to create.

Risk Profiles

Risk profiles provide administrators with a mechanism to calculate the “risk” of an authentication request based on administrator-defined attributes. For example: creating a risk profile which examines the IPv4 address of an incoming request to identify the location (continent, country, region, etc.) that the request is coming from, and conditionally enforcing addition authentication requirements for more “risky” requests.

Attributes

Attributes allow an administrator to source information about a user from a number of different sources to build up credential attributes, which can then be used by subsequent authentication/authorization flows.

class src.ibmvia_autoconf.access_control.AAC_Configurator.Attributes

Example:

attributes:
  - name: "urn:ibm:demo:transferamount"
    description: "Verify Demo Transfer Amount"
    uri: "urn:ibm:demo:transferamount"
    type:
      risk: true
      policy: false
    datatype: "Double"
    issuer: ""
    category: "Action"
    matcher: "1"
    storage:
      session: true
      behavior: false
      device: true

class Storage

behavior: bool: True if historic data for this attribute is stored in the database and used for behavior-based attribute matching.

device: bool: True if the attribute is stored when a device is registered as part of the device fingerprint.

session: bool: True if the attribute is collected in the user session. Session attributes are stored temporarily until the session times out.

class Type

policy: bool: True if the attribute is used in policies.

risk: bool: True if the attribute is used in risk profiles.

category: str: The part of the XACML request that the attribute value comes from Subject, Environment, Action or Resource.

datatype: str: The type of values that the attribute can accept String, Integer, Double, Boolean, Time, Date or X500Name.

description: str | None: An optional description of the attribute

issuer: str | None: The name of the policy information point from which the value of the attribute is retrieved.

matcher: str: ID of the attribute matcher that is used to compare the value of this attribute in an incoming device fingerprint with an existing device fingerprint of the user.

name: str: A unique name for the attribute.

storage: Storage: Define where the attribute is stored.

type: Type: Type of attribute being used.

uri: str: The identifier of the attribute that is used in the generated XACML policy.

Obligations

Obligations are used to enforce business requirements (such as registering a device) during an authorization flow before permitting access.

class src.ibmvia_autoconf.access_control.AAC_Configurator.Obligations

Example:

obligations:
- name: "myObligation"
  description: "Test obligation"
  type: "Obligation"
  uri: "urn:ibm:security:obligation:myObligation"
  parameters:
  - name: "userid"
    label: "userid"
    datatype: "String"

class Obligation

class Parameter

datatype: str: Data type for the parameter. Valid values are Boolean, Date, Double, Integer, String, Time, or X500Name.

label: str: Label for the parameter. Set it to the value of the name.

name: str: A unique name for the parameter.

class Property

key: str: A unique key for the property.

value: str: The value for the property.

description: str | None: An optional description of the obligation.

name: str: A unique name for the obligation.

parameters: List[Parameter]: Array of parameters associated with the obligation.

properties: List[Property] | None: Array of properties associated with the obligations.

type: str | None: Should be set to “Obligation”.

type_id: str | None: The obligation type id. If not provided, the value will be set to 1, which is the Enforcement Point type.

uri: str: The identifier of the obligation that is used in generated XACML.

obligations: List[Obligation]: List of access control obligations to create.

Point Of Contact

To configure Point of Contact profiles, see the entry in the Appliance or Container documentation.

Policy Information Points

Policy Information Points allow administrators to integrate third party information sources to provide additional context to an authorization policy before making a decision to permit/deny access.

class src.ibmvia_autoconf.access_control.AAC_Configurator.Policy_Information_Points

Example:

pips:
- name: "myJSpip"
  description: "Custom JavaScript PIP."
  type: "JavaScript"
  properties:
  - read_only: false
    value: |
        /** Import packages necessary for the script to execute. */
        importPackage(com.ibm. . .);
        /** Your code here */
        ....
        var name = getName();
        return
    datatype: "JavaScript"
    key: "javascript.code"
    sensitive: false
  - read_only: false
    value: "89"
    datatype: "Integer"
    key: "limit"
    sensitive: false

class Policy_Information_Point

class Attribute_Selector

name: str: Name of the attribute whose value will come from the selected data portion of the policy information point response. The attribute must be defined on the appliance before it can be assigned to this selector.

selector: str: Identifies how to select the part of the policy information point response that will be assigned as the attribute value. The format of the selector for a RESTful Web Service policy information point is dependent on the responseFormat property value, JSON", ``XML, or Text.

class Property

datatype: str: Data type of the property. Valid values include Binary, Boolean, Double, Integer, String, JavaScript, KeyStore, Email, X500, URI, URL, and Hostname.

key: str: Name of the property as used by the policy information point. A key of javascript.code or fileContent identify special properties whose values can be imported and exported by a file.

read_only: bool: True if the property value cannot be updated.

sensitive: bool: Used internally to indicate properties with values private in nature, such as passwords.

value: str: Value given to the property.

attributes: List[Attribute_Selector]: A list of custom attributes whose values are retrieved from select portions of the response from this policy information point. Specify when the policy information point type of this policy information point has supportSelector true.

description: str | None: A description of the policy information point.

name: str: A unique name for the policy information point. This name is used as the Issuer for custom attributes whose value is returned by this policy information point.

properties: List[Property]: Configurable properties defining this policy information point. These entries are specific to the policy information point type.

type: str: The policy information point type for this policy information point. Valid types include JavaScript, RESTful Web Service, Database, LDAP, FiberLink MaaS360, and QRadar User Behavior Analytics.

pips: List[Policy_Information_Point]: List of policy information points to configure.

HTTP Template Files

To upload HTTP template files, see the entry in the Appliance or Container documentation.

JavaScript Mapping Rules

To upload JavaScript mapping rules, see the entry in the Appliance or Container documentation.

Push Notification Service

This configuration option can be used to integrate with Apple/Google mobile push notification service.

class src.ibmvia_autoconf.access_control.AAC_Configurator.Push_Notification_Provider

Example:

push_notification_providers:
- platform: "android"
  app_id: "com.ibm.security.verifyapp"
  provider: "imc"
  provider_address: "verifypushcreds.mybluemix.net"
  imc_app_key: !secret default/isva-secrets:android_app_key
  imc_client_id: !secret default/isva-secrets:android_client_id
  imc_client_secret: !secret default/isva-secrets:android_client_secret
  imc_refresh_token: !secret default/isva-secrets:android_refresh_token
- platform: "apple"
  app_id: "com.ibm.security.verifyapp"
  provider: "imc"
  provider_address: "verifypushcreds.mybluemix.net"
  imc_app_key: !secret default/isva-secrets:apple_app_key
  imc_client_id: !secret default/isva-secrets:apple_client_id
  imc_client_secret: !secret default/isva-secrets:apple_client_secret
  imc_refresh_token: !secret default/isva-secrets:apple_refresh_token

app_id: str: The application identifier associated with the registration.

apple_key_label: str | None: The key label of the imported APNS certificate. Only valid if platform is apple.

apple_key_store: str | None: The key store database containing the APNS certificate. Only valid if platform is apple.

firebase_server_key: str | None: The server key for access to the Firebase push notification service. Only valid if platform is android.

imc_app_key: str | None: The app key issued by IBM Marketing Cloud for the associated application.

imc_client_id: str | None: The IBM Marketing Cloud issued Oauth client ID.

imc_client_secret: str | None: The IBM Marketing Cloud issued Oauth client secret.

imc_refresh_token: str | None: The IBM Marketing Cloud issued Oauth refresh token.

platform: str: The platform the registration is for. Valid values are apple, or android.

provider_address: str: The host:port address of the push notification service provider.

Mobile Multi-Factor Authentication

Configure MMFA capabilities. These properties are used as a discovery mechanism for devices which have been registered for a user; and is capable of initiating or completing an “out of band” authentication/authorization challenge.

class src.ibmvia_autoconf.access_control.AAC_Configurator.Mobile_Multi_Factor_Authentication

Example:

mmfa:
  client_id: "IBMVerify"
  hostname: "https://www.myidp.ibm.com"
  port: 444
  options: "ignoreSslCerts=true"
  junction: "/mga"
  discovery_mechanisms:
  - "urn:ibm:security:authentication:asf:mechanism:totp"
  - "urn:ibm:security:authentication:asf:mechanism:mobile_user_approval:user_presence"
  - "urn:ibm:security:authentication:asf:mechanism:mobile_user_approval:fingerprint"

class Endpoints

authntrxn_endpoint: str: The SCIM Transaction endpoint returned from the discovery endpoint.

details_url: str: The discovery endpoint included in the registration QR code.

enrollment_endpoint: str: The enrollment endpoint returned from the discovery endpoint.

hotp_shared_secret_endpoint: str: The HOTP shared secret endpoint returned from the discovery endpoint.

mobile_endpoint_prefix: str: The prefix of the runtime endpoint that is constructed and saved as the requestUrl of a transaction.

qrlogin_endpoint: str: The QR Code login endpoint returned from the discovery endpoint.

token_endpoint: str: The OAuth token endpoint returned from the discovery endpoint.

totp_shared_secret_endpoint: str: The TOTP shared secret endpoint returned from the discovery endpoint.

client_id: str: The OAuth client ID required for the MMFA service.

discovery_mechanisms: List[str] | None: A list of authentication mechanism URIs to be included in the discovery endpoint response.

endpoints: Endpoints | None: An object containing the endpoints returned from the registration QR code or the discovery endpoint. If configured, overwrites hostname, port, and junction configuration.

hostname: str | None: The hostname of the MMFA endpoint URI. Protocol used will be https. Must be configured if endpoints is not included

junction: str | None: The junction of the MMFA endpoint URI. Must be configured if endpoints is not included.

options: str | None: A list of configurable key-value pairs to be presented in the QR code. Recommended formatting key=value,key=value.

port: int | None: The port of the MMFA endpoint URI. Must be configured if endpoints is not included.

Server Connections

To configure third party Server Connections, see the entry in the Appliance or Container documentation.

Advanced Configuration Parameters

To set Advanced Configuration Properties, see the entry in the Appliance or Container documentation.

SCIM

This configuration property is used to configure Verify Identity Access to integrate with either a LDAP server or a Verify Identity Access User Registry (WebSEAL runtime component) using the System for Cross-Domain Identity Management interfaces. This allows administrators to create/manage users, as well as provide attributes to other Verify Identity Access authentication components.

class src.ibmvia_autoconf.access_control.AAC_Configurator.System_CrossDomain_Identity_Management

Example:

scim:
  admin_group: "SecurityGroup"
  schemas:
  - schema: "urn:ietf:params:scim:schemas:core:2.0:User"
    properties:
      connection_type: "ldap"
      ldap_connection: "Local LDAP connection"
      search_suffix: "dc=ibm,dc=com"
      user_suffix: "dc=ibm,dc=com"
  attribute_modes:
  - schema: "urn:ietf:params:scim:schemas:extension:isam:1.0:MMFA:Transaction"
    modes:
    - attribute: "transactionsPending"
      mode: "readwrite"
    - attribute: "transactionsPending"
      subattribute: "txnStatus"
      mode: "readwrite"

class AttributeMode

class Mode

attribute: str: The name of the attribute.

mode: str: The mode for the attribute. Valid value include readonly, writeonly, readwrite, adminwrite or immutable.

subatttribute: str: For a multivalued attribute - the second level SCIM attribute name.

modes: List[Mode]: An array of customised attribute modes for the schema.

schema: str: The name of the schema.

class Schema

class EnterpriseSchemaProperties

uri: urn:ietf:params:scim:schemas:extension:enterprise:2.0:User

class SCIMMapping

class Mapping

scim_subattribute: str: For a multivalued attribute - the second level SCIM attribute name to be mapped. eg. work or home for SCIM attribute email.

source: str: The attribute to map to the SCIM attribute.

type: str: The type of attribute to map to the SCIM attribute. Valid vales include ldap, session or fixed.

mapping: Mapping: For a simple SCIM attribute - the mapping for this attribute. For a complex SCIM attribute this can be an array of mappings.

scim_attribute: str: The name of the SCIM attribute being mapped.

mappings: List[SCIMMapping]: The list of SCIM enterprise user attribute mappings.

class GroupSchemaProperties

uri: urn:ietf:params:scim:schemas:core:2.0:Group

class LDAPObjectClass

name: str: The name of the ldap object class type that is used to indicate a user object.

group_dn: str: The LDAP attribute that will be used to construct the group DN.

ldap_object_classes: List[LDAPObjectClass]: The list of ldap object classes that are used to indicate a group object.

class IVIAUserSchemaProperties

uri: urn:ietf:params:scim:schemas:extension:isam:1.0:User

attrs_dir: str | None: The name of a federated directory used to generate the list of available ldap object classes and ldap attribute names. Only valid if the connection_type is set to isamruntime. Default is not set.

connection_type: str | None: Indicates the type of ldap server connection ldap or isamruntime. Defaults to ldap.

enforce_password_policy: bool | None: Set this field to true if SCIM needs to honour the backend password policy when changing a user password. Defaults to false.

isam_domain: str | None: The name of the Verify Identity Access domain. This will default to Default

ldap_connection: str | None: The name of the ldap server connection to the Verify Identity Access user registry. If a connection is not specified the SCIM application will not attempt to manage Verify Identity Access users.

update_native_users: bool | None: Enable update of Verify Identity Access specific attributes when LDAP standard attributes are updated.

class UserSchemaProperties

uri: urn:ietf:params:scim:schemas:core:2.0:User

class LDAPObjectClass

name: str: The name of the ldap object class type that is used to indicate a user object.

class SCIMMapping

class Mapping

scim_subattribute: str: For a multivalued attribute - the second level SCIM attribute name to be mapped. eg. work or home for SCIM attribute email.

source: str: The attribute to map to the SCIM attribute.

type: str: The type of attribute to map to the SCIM attribute. Valid values are ldap, session or fixed.

mapping: Mapping: For a simple SCIM attribute - the mapping for this attribute. For a complex SCIM attribute this can be an array of mappings.

scim_attribute: str: The name of the SCIM attribute being mapped.

attrs_dir: str | None: The name of a federated directory used to generate the list of available ldap object classes and ldap attribute names. Only valid if the connection_type is set to isamruntime.

connection_type: str | None: Indicates the type of ldap server connection type. Valid values include ldap and isamruntime. Defaults to ldap

enforce_password_policy: bool: Set this field to true if SCIM needs to honour the backend password policy when changing a user password.

ldap_connection: str: The name of the ldap server connection.

ldap_object_classes: List[LDAPObjectClass]: The list of ldap object classes that are used to indicate a user object.

mappings: List[SCIMMapping] | None: The list of SCIM attribute mappings.

search_suffix: str: The suffix from which searches will commence in the LDAP server.

user_dn: str | None: The LDAP attribute that will be used to construct the user DN. Defaults to cn.

user_id: str | None: The LDAP attribute that will be used as the user ID. Defaults to uid.

user_suffix: str: The suffix that will house any users that are created through the SCIM interface.

properties: IVIAUserSchemaProperties | GroupSchemaProperties | EnterpriseSchemaProperties | UserSchemaProperties: Schema unique properties to apply.

uri: str: Name of schema properties to modify. See .*SchemaProperties classes for the valid schema names.

admin_group: str: The name of the administrator group. Used to determine if the authenticated user is an administrator.

attribute_modes: List[AttributeMode] | None: The customized attribute modes.

enable_authz_filter: bool | None: Whether or not the authorization filter is enabled.

enable_header_authentication: bool | None: Whether or not SCIM header authentication is enabled.

max_user_response: int | None: The maximum number of entries that can be returned from a single call to the /User endpoint.

schemas: List[Schema] | None: List of managed schema to modify

FIDO2

The FIDO2 configuration property is used to create and manage FIDO2 relying parties and their associated verification documents (metadata) as well as any custom logic applied in a JavaScript mediator.

class src.ibmvia_autoconf.access_control.AAC_Configurator.Fast_Identity_Online2

Example:

fido2:
  relying_parties:
  - name: "fidointerop.securitypoc.com"
    rp_id: "fidointerop.securitypoc.com"
    origins:
    - "https://fidointerop.securitypoc.com"
    - "urn:ibm:security:verify:app:namespace"
    use_all_metadata: true
    metadata_soft_fail: false
    metadata_services:
    - url: "https://mds3.fidoalliance.org"
      truststore: "rt_profile_keys"
      jws_truststore: "fido_mds_certs"
    mediator: "fido2_mediator_verifysecuritypoc.js"
    attestation:
      statement_types:
      - "basic"
      - "self"
      - "attCA"
      - "anonCA"
      - "none"
      statement_formats:
      - "fido-u2f"
      - "packed"
      - "self"
      - "android-key"
      - "android-safetynet"
      - "tpm"
      - "none"
  metadata:
    metadata:
    - "fido2/metadata"
    metadata_services:
    - url: "https://mds.fidoalliance.org"
      timeout: 30

class Metadata

class Metadata_Service

class Header

name: str: The name of the HTTP header.

value: str: The value of the HTTP header.

certificate: str | None: The client key alias. If not specified client certificate authentication will not be used.

headers: List[Header] | None: A list of HTTP headers to be added to the HTTP request when retrieving the metadata from the service.

jws_truststore: str | None: The name of the JWS verification truststore. The truststore contains the certificate used to verify the signature of the downloaded metadata blob. If not specified the SSL trust store or the trust store configured in the HTTPClientV2 advanced configuration will be used.

keystore: str | None: The client keystore. If not specified client certificate authentication will not be used.

password: str | None: The basic authentication password. If not specified BA will not be used.

protocol: str | None: The SSL protocol to use for the HTTPS connection. Valid values are TLS, TLSv1, TLSv1.1 and TLSv1.2. If not specified the protocol configured in the HTTPClientV2 advanced configuration will be used.

proxy: str | None: The URL of the proxy server used to connect to the metadata service (including the protocol).

retry_interval: int | None: When the lifetime of a downloaded metadata has expired and a request to retrieve the new metadata fails, this defines the wait interval (in seconds) before retrying the download. If not specified the default value of 3600 seconds will be used. A value of 0 will result in a retry on each attestation validation.

timeout: int | None: The request timeout in seconds. A value of 0 will result in no timeout. If not specified the connect timeout configured in the HTTPClientV2 advanced configuration will be used.

truststore: str | None: The name of the truststore to use. The truststore has a dual purpose. Firstly it is used when making a HTTPS connection to the Metadata Service. Secondly if the jwsTruststore is not specified it must contain the certificate used to verify the signature of the downloaded metadata blob. If not specified and a HTTPS connection is specified, the trust store configured in the HTTPClientV2 advanced configuration will be used.

url: str: Address of the metadata service.

username: str | None: The basic authentication username. If not specified BA will not be used.

metadata: List[str] | None: List of metadata documents to enable for the relying party.

metadata_services: List[Metadata_Service] | None: List of metadata services to enable for the relying party.

class Relying_Party

class Android

clock_skew: int: Maximum allowed clock skew in signed attestation attributes.

cts_profile_match: bool | None: True if the Android SafetyNet CTS Profile Match flag should be enforced. Default is true.

max_age: int: Maximum age of attestation signature.

class Attestation

compound_all_valid: bool | None: True if all attestation statements in a compound attestation must be valid to successfuly register an authenticator. Default value is true.

public_key_algorithms: List[str] | None: List of COSE algorithm identifiers to permit.

statement_formats: List[str] | None: List of attestation formats to permit.

statement_types: List[str] | None: List of attestation types to permit.

android: Android | None: Androind attestation specific configuration.

attestation: Attestation | None: Attestation properties permitted for this relying party.

impersonation_group: str | None: Group used to permit admin operations for this relying party.

mediator: str | None: Mediator mappign rule to configure for this relying party.

metadata: List[str] | None: List of metadata documents to enable for this relying party.

metadata_services: str | None: List of metadata services to enable for this relying party.

name: str: Name of the relying party.

origins: List[str]: List of permitted origins. These should be valid sub-domains of the rp_id.

rp_id: str: URI of the relying party base domain.

timeout: int | None: Time period a user has to complete a FIDO2/WebAuthn ceremony. Default value is 300 seconds.

use_all_metadata: bool | None: Use all available metadata documents for this relying party.

mediators: List[str] | None: JavaScript files to upload as FIDO2 mediators.

metadata: Metadata | None: Files to upload as static FIDO2 metadata documents.

relying_parties: List[Relying_Party] | None: List of relying parties to configure.

Runtime Server Configuration

To set Runtime Server properties, see the entry in the Appliance or Container documentation.