Jump to

• Request
• Response

Create an Authentication Type Instance

post

/api/AAA/AuthTypes

Creates a new authentication type instance. You can create multiple instances of the SAML, LDAP, and Active Directory authentication types. There will always be only one Internal authentication type instance.
The minimum required properties in the request body are:

• AuthenticationTypeName
• AuthenticationTypeProtocol
• AuthenticationStatus
• If AuthenticationTypeProtocol is SAML:
  • Certificate
  • EntityID
  • SingleLogoutService
  • SingleSignOnService
• If AuthenticationTypeProtocol is LDAP:
  • LDAPHost1
• If AuthenticationTypeProtocol is Active Directory:
  • ADHost1

Request

There are no request parameters for this operation.

Supported Media Types

• application/json

Request Body - application/json ()

Root Schema : schema

Type: object

The details of the authentication type instance to create.

Show Source

• ADHost1: string
  The IP or FQDN of the primary server to use for Active Directory. Used for the Active Directory authentication type only.

  Example: ad1.example.com
• ADHost2: string
  The IP or FQDN of the failover server to use for Active Directory. Used for the Active Directory authentication type only.

  Example: ad2.example.com
• ADSecureConnection: integer
  Whether to connect to Active Directory over a secure connection (1) or not (0). Used for the Active Directory authentication type only.

  Example: 1
• AuthenticationDomain: string
  The domain to use for transient users. Also used for persistent Active Directory users.

  Example: ad.example.com
• AuthenticationStatus: boolean
  Whether the authentication type instance is enabled (1) or not (0).

  Example: 1
• AuthenticationTypeName: string
  The authentication type instance name. Use this to differentiate between multiple instances of the same protocol.
  To avoid confusion with numeric IDs, the name value cannot be integers only or integers prefixed with the + or - symbols only. It must contain letters or other characters. For example, 1234, +1234, and -1234 are not valid, but US1234, US+1234 and US_1234 are.

  Example: SAML SSO 1
• AuthenticationTypeProtocol: string
  The protocol used for the authentication type instance. Valid values are:

  • SAML
  • LDAP
  • Active Directory

  The Internal authentication type instance exists by default, and you cannot create more of that type.

  Example: SAML
• Certificate: string
  The SAML certificate. Used for the SAML authentication type only.
• DefaultInstance: boolean
  Whether or not (1 or 0) to use this LDAP or Active Directory instance to authenticate when the username or domain specified at login does not match any of the other configured authentication protocols. There can only be one default instance. Used for the LDAP and Active Directory authentication types only.

  Example: 1
• EntityID: string
  The unique ID for your SAML-enabled identity provider. Used for the SAML authentication type only.

  Example: example.com/saml-idp
• GroupField: string
  The field to look for user groups for transient users. The value can vary by authentication provider. For example, LDAP uses memberOf, and SAML might use member, eduPersonAffiliation, or any string. Used when authenticating transient users with external authentication types only.

  Example: memberOf
• LDAPDN: string
  The LDAP distinguished name (dn) specific to your organization. Use %s as a variable for usernames. Used for the LDAP authentication type only.

  Example: CN=%s,OU=Users,DC=example,DC=com
• LDAPHost1: string
  The IP or FQDN of the primary server to use for LDAP. Used for the LDAP authentication type only.

  Example: ldap.example.com
• LDAPHost2: string
  The IP or FQDN of the secondary server to use for LDAP. Used for the LDAP authentication type only.

  Example: ldap2.example.com
• LDAPPort: integer
  Optional. The port to use for LDAP. Used for the LDAP authentication type only.

  Example: 636
• LDAPSecureConnection: integer
  The type of secure connection for LDAP. Valid values are:

  • 0: None (do not use a secure connection)
  • 1: LDAPS (secure on connection)
  • 2: TLS (negotiated)

  Used for the LDAP authentication type only.

  Example: 1
• NameIDFormat: string
  The format of the name ID element of the SAML response. The Unified Assurance username for persistent users must match this format. Used for the SAML authentication type only.

  Example: urn:oasis:names:tc:SAML:2.0:nameid-format:persistent
• SingleLogoutService: string
  The endpoint on your IdP that receives incoming logout requests and sends logout responses. Used for the SAML authentication type only.

  Example: example.com/saml/saml2/idp/SingleLogoutService.php
• SingleSignOnService: string
  The endpoint on your IdP that receives authentication requests, processes them, and returns the authenticated user. Used for the SAML authentication type only.

  Example: example.com/saml/saml2/idp/SSOService.php

{
    "properties":{
        "AuthenticationDomain":{
            "description":"The domain to use for transient users. Also used for persistent Active Directory users.",
            "type":"string",
            "example":"ad.example.com"
        },
        "ADHost1":{
            "description":"The IP or FQDN of the primary server to use for Active Directory. Used for the Active Directory authentication type only.",
            "type":"string",
            "example":"ad1.example.com"
        },
        "ADHost2":{
            "description":"The IP or FQDN of the failover server to use for Active Directory. Used for the Active Directory authentication type only.",
            "type":"string",
            "example":"ad2.example.com"
        },
        "ADSecureConnection":{
            "description":"Whether to connect to Active Directory over a secure connection (<b>1</b>) or not (<b>0</b>). Used for the Active Directory authentication type only.",
            "type":"integer",
            "example":"1"
        },
        "AuthenticationTypeName":{
            "description":"The authentication type instance name. Use this to differentiate between multiple instances of the same protocol.\n<br>To avoid confusion with numeric IDs, the name value cannot be integers only or integers prefixed with the + or - symbols only. It must contain letters or other characters. For example, <b>1234</b>, <b>+1234</b>, and <b>-1234</b> are not valid, but <b>US1234</b>, <b>US+1234</b> and <b>US_1234</b> are.",
            "type":"string",
            "example":"SAML SSO 1"
        },
        "AuthenticationTypeProtocol":{
            "description":"The protocol used for the authentication type instance. Valid values are: <ul><li>SAML</li><li>LDAP</li><li>Active Directory</li></ul> The Internal authentication type instance exists by default, and you cannot create more of that type.",
            "type":"string",
            "example":"SAML"
        },
        "AuthenticationStatus":{
            "description":"Whether the authentication type instance is enabled (<b>1</b>) or not (<b>0</b>).",
            "type":"boolean",
            "example":"1"
        },
        "Certificate":{
            "description":"The SAML certificate. Used for the SAML authentication type only.",
            "type":"string"
        },
        "DefaultInstance":{
            "description":"Whether or not (<b>1</b> or <b>0</b>) to use this LDAP or Active Directory instance to authenticate when the username or domain specified at login does not match any of the other configured authentication protocols. There can only be one default instance. Used for the LDAP and Active Directory authentication types only.",
            "type":"boolean",
            "example":"1"
        },
        "EntityID":{
            "description":"The unique ID for your SAML-enabled identity provider. Used for the SAML authentication type only.",
            "type":"string",
            "example":"example.com/saml-idp"
        },
        "GroupField":{
            "description":"The field to look for user groups for transient users. The value can vary by authentication provider. For example, LDAP uses <b>memberOf</b>, and SAML might use <b>member</b>, <b>eduPersonAffiliation</b>, or any string. Used when authenticating transient users with external authentication types only.",
            "type":"string",
            "example":"memberOf"
        },
        "LDAPDN":{
            "description":"The LDAP distinguished name (dn) specific to your organization. Use <b>%s</b> as a variable for usernames. Used for the LDAP authentication type only.",
            "type":"string",
            "example":"CN=%s,OU=Users,DC=example,DC=com"
        },
        "LDAPHost1":{
            "description":"The IP or FQDN of the primary server to use for LDAP. Used for the LDAP authentication type only.",
            "type":"string",
            "example":"ldap.example.com"
        },
        "LDAPHost2":{
            "description":"The IP or FQDN of the secondary server to use for LDAP. Used for the LDAP authentication type only.",
            "type":"string",
            "example":"ldap2.example.com"
        },
        "LDAPPort":{
            "description":"Optional. The port to use for LDAP. Used for the LDAP authentication type only.",
            "type":"integer",
            "example":"636"
        },
        "LDAPSecureConnection":{
            "description":"The type of secure connection for LDAP. Valid values are: <ul><li><b>0</b>: None (do not use a secure connection)</li><li><b>1</b>: LDAPS (secure on connection)</li><li><b>2</b>: TLS (negotiated)</li></ul> Used for the LDAP authentication type only.",
            "type":"integer",
            "example":"1"
        },
        "NameIDFormat":{
            "description":"The format of the name ID element of the SAML response. The Unified Assurance username for persistent users must match this format. Used for the SAML authentication type only.",
            "type":"string",
            "example":"urn:oasis:names:tc:SAML:2.0:nameid-format:persistent"
        },
        "SingleLogoutService":{
            "description":"The endpoint on your IdP that receives incoming logout requests and sends logout responses. Used for the SAML authentication type only.",
            "type":"string",
            "example":"example.com/saml/saml2/idp/SingleLogoutService.php"
        },
        "SingleSignOnService":{
            "description":"The endpoint on your IdP that receives authentication requests, processes them, and returns the authenticated user. Used for the SAML authentication type only.",
            "type":"string",
            "example":"example.com/saml/saml2/idp/SSOService.php"
        }
    },
    "type":"object",
    "description":"The details of the authentication type instance to create."
}

Back to Top

Response

Supported Media Types

• application/json

200 Response

Successful operation

Body ()

Root Schema : schema

Match All

Show Source

• object SuccessfulAddOperation
  The response body for a successful add operation.
• object type

{
    "allOf":[
        {
            "$ref":"#/components/schemas/SuccessfulAddOperation"
        },
        {
            "type":"object",
            "properties":{
                "total":{
                    "description":"The total number of results regardless of paging.",
                    "type":"integer",
                    "example":"1"
                },
                "data":{
                    "type":"array",
                    "items":{
                        "$ref":"#/components/schemas/AAAAuthTypesRead"
                    }
                }
            }
        }
    ]
}

Nested Schema : SuccessfulAddOperation

Type: object

The response body for a successful add operation.

Show Source

• message: string
  The response message.

  Example: Added record
• success: boolean
  Whether the operation was a success (true) or a failure (false).

  Example: true

{
    "description":"The response body for a successful add operation.",
    "properties":{
        "success":{
            "description":"Whether the operation was a success (<b>true</b>) or a failure (<b>false</b>).",
            "type":"boolean",
            "example":"true"
        },
        "message":{
            "description":"The response message.",
            "type":"string",
            "example":"Added record"
        }
    },
    "type":"object"
}

Nested Schema : type

Type: object

Show Source

• data: array data
• total: integer
  The total number of results regardless of paging.

  Example: 1

{
    "type":"object",
    "properties":{
        "total":{
            "description":"The total number of results regardless of paging.",
            "type":"integer",
            "example":"1"
        },
        "data":{
            "type":"array",
            "items":{
                "$ref":"#/components/schemas/AAAAuthTypesRead"
            }
        }
    }
}

Nested Schema : data

Type: array

Show Source

• Array of: object AAAAuthTypesRead
  The authentication type instance details.

{
    "type":"array",
    "items":{
        "$ref":"#/components/schemas/AAAAuthTypesRead"
    }
}

Nested Schema : AAAAuthTypesRead

Type: object

The authentication type instance details.

Show Source

• ADHost1: string
  The IP or FQDN of the primary server to use for Active Directory. Used for the Active Directory authentication type only.

  Example: ad1.example.com
• ADHost2: string
  The IP or FQDN of the failover server to use for Active Directory. Used for the Active Directory authentication type only.

  Example: ad2.example.com
• ADSecureConnection: integer
  Whether to connect to Active Directory over a secure connection (1) or not (0). Used for the Active Directory authentication type only.

  Example: 1
• AuthenticationDomain: string
  The domain to use for transient users. Also used for persistent Active Directory users.

  Example: ad.example.com
• AuthenticationStatus: boolean
  Whether the authentication type instance is enabled (1) or not (0).

  Example: 1
• AuthenticationStatusIcon: string
  The authentication type instance status icon.

  Example: OrbGreen.png
• AuthenticationTypeID: integer
  The authentication type instance ID.

  Example: 1
• AuthenticationTypeName: string
  The authentication type instance name. Use this to differentiate between multiple instances of the same protocol.

  Example: SAML SSO 1
• AuthenticationTypeProtocol: string
  The protocol used for the authentication type instance. Valid values are:

  • SAML
  • LDAP
  • Active Directory
  • Internal

  Example: SAML
• Certificate: string
  The SAML certificate. Used for the SAML authentication type only.
• DefaultInstance: boolean
  Whether or not (1 or 0) to use this LDAP or Active Directory instance to authenticate when the username or domain specified at login does not match any of the other configured authentication protocols. There can only be one default instance. Used for the LDAP and Active Directory authentication types only.

  Example: 1
• EntityID: string
  The unique ID for your SAML-enabled identity provider. Used for the SAML authentication type only.

  Example: example.com/saml-idp
• GroupField: string
  The field to look for user groups for transient users. The value can vary by authentication provider. For example, LDAP uses memberOf, SAML might use member, eduPersonAffiliation, or any string. Used when authenticating transient users with external authentication types only.

  Example: memberOf
• LDAPDN: string
  The LDAP distinguished name (dn) specific to your organization. Use %s as a variable for usernames. Used for the LDAP authentication type only.

  Example: CN=%s,OU=Users,DC=example,DC=com
• LDAPHost1: string
  The IP or FQDN of the primary server to use for LDAP. Used for the LDAP authentication type only.

  Example: ldap.example.com
• LDAPHost2: string
  The IP or FQDN of the secondary server to use for LDAP. Used for the LDAP authentication type only.

  Example: ldap2.example.com
• LDAPPort: integer
  Optional. The port to use for LDAP. Used for the LDAP authentication type only.

  Example: 636
• LDAPSecureConnection: integer
  The type of secure connection for LDAP. Valid values are:

  • 0: None (do not use a secure connection)
  • 1: LDAPS (secure on connection)
  • 2: TLS (negotiated)

  Used for the LDAP authentication type only.

  Example: 1
• NameIDFormat: string
  The format of the name ID element of the SAML response. The Unified Assurance username for persistent users must match this format. Used for the SAML authentication type only.

  Example: urn:oasis:names:tc:SAML:2.0:nameid-format:persistent
• PasswordMinimumLength: integer
  The minimum password length. Used for the Internal authentication type only.

  Example: 4
• PasswordRequiredLowercase: integer
  The minimum number of lowercase letters required in the password. Used for the Internal authentication type only.

  Example: 1
• PasswordRequiredNumbers: integer
  The minimum number of numerals required in the password. Used for the Internal authentication type only.

  Example: 0
• PasswordRequiredSpecialCharacters: integer
  The minimum number of special characters required in the password. Used for the Internal authentication type only.

  Example: 0
• PasswordRequiredUppercase: integer
  The minimum number of uppercase letters required in the password. Used for the Internal authentication type only.

  Example: 0
• PasswordResetAvailable: integer
  The number of password resets available. Used for the Internal authentication type only.

  Example: 0
• PasswordResetCustomText: string
  Custom text to show when resetting a password. This is used for internal authentication only.

  Example: Reset password
• PasswordResetQuestion1: string
  The question to ask a user when they reset their password. This is used for internal authentication only.

  Example: What was the name of your first pet?
• SingleLogoutService: string
  The endpoint on your IdP that receives incoming logout requests and sends logout responses. Used for the SAML authentication type only.

  Example: example.com/saml/saml2/idp/SingleLogoutService.php
• SingleSignOnService: string
  The endpoint on your IdP receives authentication requests, processes them, and returns the authenticated user. Used for the SAML authentication type only.

  Example: example.com/saml/saml2/idp/SSOService.php

{
    "properties":{
        "AuthenticationDomain":{
            "description":"The domain to use for transient users. Also used for persistent Active Directory users.",
            "type":"string",
            "example":"ad.example.com"
        },
        "ADHost1":{
            "description":"The IP or FQDN of the primary server to use for Active Directory. Used for the Active Directory authentication type only.",
            "type":"string",
            "example":"ad1.example.com"
        },
        "ADHost2":{
            "description":"The IP or FQDN of the failover server to use for Active Directory. Used for the Active Directory authentication type only.",
            "type":"string",
            "example":"ad2.example.com"
        },
        "ADSecureConnection":{
            "description":"Whether to connect to Active Directory over a secure connection (<b>1</b>) or not (<b>0</b>). Used for the Active Directory authentication type only.",
            "type":"integer",
            "example":"1"
        },
        "AuthenticationTypeID":{
            "description":"The authentication type instance ID.",
            "type":"integer",
            "example":"1"
        },
        "AuthenticationTypeName":{
            "description":"The authentication type instance name. Use this to differentiate between multiple instances of the same protocol.",
            "type":"string",
            "example":"SAML SSO 1"
        },
        "AuthenticationTypeProtocol":{
            "description":"The protocol used for the authentication type instance. Valid values are: <ul><li>SAML</li><li>LDAP</li><li>Active Directory</li><li>Internal</li></ul>",
            "type":"string",
            "example":"SAML"
        },
        "AuthenticationStatusIcon":{
            "description":"The authentication type instance status icon.",
            "type":"string",
            "example":"OrbGreen.png"
        },
        "AuthenticationStatus":{
            "description":"Whether the authentication type instance is enabled (<b>1</b>) or not (<b>0</b>).",
            "type":"boolean",
            "example":"1"
        },
        "Certificate":{
            "description":"The SAML certificate. Used for the SAML authentication type only.",
            "type":"string"
        },
        "DefaultInstance":{
            "description":"Whether or not (<b>1</b> or <b>0</b>) to use this LDAP or Active Directory instance to authenticate when the username or domain specified at login does not match any of the other configured authentication protocols. There can only be one default instance. Used for the LDAP and Active Directory authentication types only.",
            "type":"boolean",
            "example":"1"
        },
        "EntityID":{
            "description":"The unique ID for your SAML-enabled identity provider. Used for the SAML authentication type only.",
            "type":"string",
            "example":"example.com/saml-idp"
        },
        "GroupField":{
            "description":"The field to look for user groups for transient users. The value can vary by authentication provider. For example, LDAP uses <b>memberOf</b>, SAML might use <b>member</b>, <b>eduPersonAffiliation</b>, or any string. Used when authenticating transient users with external authentication types only.",
            "type":"string",
            "example":"memberOf"
        },
        "LDAPDN":{
            "description":"The LDAP distinguished name (dn) specific to your organization. Use <b>%s</b> as a variable for usernames. Used for the LDAP authentication type only.",
            "type":"string",
            "example":"CN=%s,OU=Users,DC=example,DC=com"
        },
        "LDAPHost1":{
            "description":"The IP or FQDN of the primary server to use for LDAP. Used for the LDAP authentication type only.",
            "type":"string",
            "example":"ldap.example.com"
        },
        "LDAPHost2":{
            "description":"The IP or FQDN of the secondary server to use for LDAP. Used for the LDAP authentication type only.",
            "type":"string",
            "example":"ldap2.example.com"
        },
        "LDAPPort":{
            "description":"Optional. The port to use for LDAP. Used for the LDAP authentication type only.",
            "type":"integer",
            "example":"636"
        },
        "LDAPSecureConnection":{
            "description":"The type of secure connection for LDAP. Valid values are: <ul><li><b>0</b>: None (do not use a secure connection)</li><li><b>1</b>: LDAPS (secure on connection)</li><li><b>2</b>: TLS (negotiated)</li></ul> Used for the LDAP authentication type only.",
            "type":"integer",
            "example":"1"
        },
        "NameIDFormat":{
            "description":"The format of the name ID element of the SAML response. The Unified Assurance username for persistent users must match this format. Used for the SAML authentication type only.",
            "type":"string",
            "example":"urn:oasis:names:tc:SAML:2.0:nameid-format:persistent"
        },
        "PasswordMinimumLength":{
            "description":"The minimum password length. Used for the Internal authentication type only.",
            "type":"integer",
            "example":"4"
        },
        "PasswordRequiredLowercase":{
            "description":"The minimum number of lowercase letters required in the password. Used for the Internal authentication type only.",
            "type":"integer",
            "example":"1"
        },
        "PasswordRequiredNumbers":{
            "description":"The minimum number of numerals required in the password. Used for the Internal authentication type only.",
            "type":"integer",
            "example":"0"
        },
        "PasswordRequiredSpecialCharacters":{
            "description":"The minimum number of special characters required in the password. Used for the Internal authentication type only.",
            "type":"integer",
            "example":"0"
        },
        "PasswordRequiredUppercase":{
            "description":"The minimum number of uppercase letters required in the password. Used for the Internal authentication type only.",
            "type":"integer",
            "example":"0"
        },
        "PasswordResetAvailable":{
            "description":"The number of password resets available. Used for the Internal authentication type only.",
            "type":"integer",
            "example":"0"
        },
        "PasswordResetCustomText":{
            "description":"Custom text to show when resetting a password. This is used for internal authentication only.",
            "type":"string",
            "example":"Reset password"
        },
        "PasswordResetQuestion1":{
            "description":"The question to ask a user when they reset their password. This is used for internal authentication only.",
            "type":"string",
            "example":"What was the name of your first pet?"
        },
        "SingleLogoutService":{
            "description":"The endpoint on your IdP that receives incoming logout requests and sends logout responses. Used for the SAML authentication type only.",
            "type":"string",
            "example":"example.com/saml/saml2/idp/SingleLogoutService.php"
        },
        "SingleSignOnService":{
            "description":"The endpoint on your IdP receives authentication requests, processes them, and returns the authenticated user. Used for the SAML authentication type only.",
            "type":"string",
            "example":"example.com/saml/saml2/idp/SSOService.php"
        }
    },
    "type":"object",
    "description":"The authentication type instance details."
}

Default Response

Failed operation

Body ()

Root Schema : schema

Type: object

Show Source

• errors: array errors
  The list of errors reported. Validation errors will be keyed by record field.
• message: string
  The response message.

  Example: Exception thrown
• success: boolean
  Whether the operation was a success (true) or a failure (false).

  Example: false

{
    "properties":{
        "success":{
            "description":"Whether the operation was a success (<b>true</b>) or a failure (<b>false</b>).",
            "type":"boolean",
            "example":"false"
        },
        "message":{
            "description":"The response message.",
            "type":"string",
            "example":"Exception thrown"
        },
        "errors":{
            "description":"The list of errors reported. Validation errors will be keyed by record field.",
            "type":"array",
            "items":{
                "description":"An error.",
                "type":"object"
            }
        }
    },
    "type":"object"
}

Nested Schema : errors

Type: array

The list of errors reported. Validation errors will be keyed by record field.

Show Source

• Array of: object items
  An error.

{
    "description":"The list of errors reported. Validation errors will be keyed by record field.",
    "type":"array",
    "items":{
        "description":"An error.",
        "type":"object"
    }
}

Nested Schema : items

Type: object

An error.

Back to Top