Purpose

Registers an external authentication service. An external authentication service can be created using a Java plugin, LDAP, OIDC, or SAML.

URL

https://<myserver>:<port>/api/admin/auth/services

Method

POST

URL Parameters

<myserver> is the hostname or IP address of the machine hosting the Hybrid Data Pipeline server for a non-load balancer deployment, or the machine hosting the load balancer for a load balancer deployment. For a non-load balancer deployment, <port> is the port number specified as the Server Access Port during deployment. For a load balancer deployment, <port> must be either 80 for http or 443 for https. Whenever port 80 or 443 are used, it is not necessary to include the port number in the URL.

Request Definition

The request definition varies depending on whether the service is a Java plugin, LDAP, OIDC, or SAML.

Request definition for Java plugin service

{
    "name": "authservice_name",
    "tenantId": tenant_id,
    "description": "authservice_description",
    "authDefinition": {
        "className": "java_plugin_classname",
    "attributes": {
       "attribute_name": "attribute_value",
       "attribute_name": "attribute_value",
       ...
    },
    "authTypeId": authtype_id
}
Property Description Usage Valid Values
"name" The name of the authentication service. Required A string that provides a name for the authentication service.
"tenantId" The ID of the tenant. Optional A valid tenant ID. If the tenant ID is not specified, the authentication service will belong to the tenant of the administrator executing the operation.
"description" The description of the authentication service. Optional A string that provides a description for the authentication service.
"authDefinition" An object that defines the authentication service. Required The authDefinition property must include the className property for a Java plugin service. The attributes property can provide useful information, such as an authentication server name, to be consumed by the authentication service.

See authDefinition Object for details.
"authTypeId" The ID of the authentication type. Required 2 must be specified for a Java plugin service.

Request definition for LDAP service

{
    "name": "authservice_name",
    "tenantId": tenant_id,
    "description": "authservice_description",
    "authDefinition": {
        "attributes": {
            "targetUrl": "LDAP_URL",
            "securityAuthentication": "LDAP_auth_mechanism",
            "securityPrincipal": "LDAP_principal",
            "securityCredentials": "LDAP_credentials"
        }
    },
    "authTypeId": authtype_id
}
Property Description Usage Valid Values
"name" The name of the authentication service. Required A string that provides a name for the authentication service.
"tenantId" The ID of the tenant. Optional A valid tenant ID. If the tenant ID is not specified, the authentication service will belong to the tenant of the administrator executing the operation.
"description" The description of the authentication service. Optional A string that provides a description for the authentication service.
"authDefinition" An object that defines the authentication service. Required For an LDAP service, the following attributes must be specified via the attributes object.
  • targetUrl
  • securityAuthentication
  • securityPrincipal
  • securityCredentials (optional)

See authDefinition Object for details.
"authTypeId" The ID of the authentication type. Required 3 must be specified for an LDAP service.

Request definition for SAML service

{
    "name": "authservice_name",
    "tenantId": tenant_id,
    "description": "authservice_description",
    "authDefinition": {
        "attributes": {
            "assertingPartySSOUrl": "SAML_server_url",
            "assertingPartyEntityId": "client_entity_id",
            "assertingPartyCertLoc": "client_certificate_location",
            "relyingPartyEntityId": "relyingparty_entity_id",
            "assertionConsumerServicePath": "SAML_service_path",
            "hdpUsernameIdentifier": "SAML_authenticated_user"
        }
    },
    "authTypeId": authtype_id
}
Property Description Usage Valid Values
"name" The name of the authentication service. Required A string that provides a name for the authentication service.
"tenantId" The ID of the tenant. Optional A valid tenant ID. If the tenant ID is not specified, the authentication service will belong to the tenant of the administrator executing the operation.
"description" The description of the authentication service. Optional A string that provides a description for the authentication service.
"authDefinition" An object that defines the authentication service. Required For an SAML service, the following attributes must be specified via the attributes object.
  • assertingPartySSOUrl
  • assertingPartyEntityId
  • assertingPartyCertLoc
  • relyingPartyEntityId (optional)
  • assertionConsumerServicePath (optional)
  • hdpUsernameIdentifier (optional)

See authDefinition Object for details.

Note: If relyingPartyEntityId or assertionConsumerServicePath are not specified, the default values are used in the payload.

If hdpUsernameIdentifier is not specified, the attribute is omitted from the payload.

"authTypeId" The ID of the authentication type. Required 4 must be specified for an SAML service.

Request definition for OIDC service

{
  "name": "authservice_name",
  "tenantId": tenant_id,
  "description": "authservice_description",
  "authDefinition": {
    "issuerUrl": "The URL used to access the OIDC server of the OpenID provider.",
    "hdpUsernameIdentifier": "The specific key in the token containing the authenticated user name.",  
      "attrValidation": {
        "type": "token_validation_method",
        "introspectAuthMethod": "authentication method_name",
        "clientid": "client_id of your registered application",
        "clientSecret": "client_secret of your application",
        "claimsToValidate": "A JSON object containing the claims in key-value pairs.",
        "otherAttributes": "Optional. Any valid JSON object."
       }
  },
    "authTypeId": authtype_id
}
Property Description Usage Valid Values
"name" The name of the authentication service. Required A string that provides a name for the authentication service.
"tenantId" The ID of the tenant. Optional A valid tenant ID. If the tenant ID is not specified, the authentication service will belong to the tenant of the administrator executing the operation.
"description" The description of the authentication service. Optional A string that provides a description for the authentication service.
"authDefinition" An object that defines the authentication service. Required

The IssuerURL is used to access the OIDC server of the OpenID provider.

The HdpUsernameIdentifier is an attribute containing the authenticated user name.

The following attributes must be specified via the attrValidation object.
  • type
  • introspectAuthMethod
  • clientId
  • clientSecret
    Note: The attributes introspectAuthMethod, ClientId, and ClientSecret are applicable only when the type is introspect.
  • claimsToValidate

See authDefinition Object for details.
"authTypeId" The ID of the authentication type. Required 5 must be specified for an OIDC service.

Sample Request Payload

Java plugin example request

{
    "name": "jplugauth",
    "tenantId": 1,
    "description": "Java external auth plugin",
    "authDefinition": {
        "className": "com.test.hdp.plugins.auth.HDPUserAuthentication",
        "attributes": {
            "Server": "test-authentication",
            "BackupServer": "test-authentication-backup"
        }
    },
    "authTypeId": 2
}

LDAP example request

{
    "name": "LDAP",
    "tenantId": 66,
    "description": "LDAP Auth plugin",
    "authDefinition": {
        "attributes": {
            "targetUrl": "LDAP://123.45.67.899:389",
            "securityAuthentication": "simple",
            "securityPrincipal": "CN=%LOGINNAME%,OU=TestRuns,DC=testdomain,DC=local"
        }
    },
    "authTypeId": 3
}

SAML example request

{
  "name": "SAML",
  "tenantId": 1,
  "description": "SAML Auth plugin",
  "authDefinition": {
    "attributes": {
      "assertingPartySSOUrl": "https://login.myserver.com/37d22137-b880-0247099d/saml",
      "assertingPartyEntityId": "https://sts.system.net/74b27217-b880-02470799266d/",
      "assertingPartyCertLoc": "Progress/DataDirect/Hybrid_Data_Pipeline/Hybrid_Server/ddcloud/keystore/",
      "relyingPartyEntityId": "https://hostname:8443/hdp/saml/service-metadata/test",
      "assertionConsumerServicePath": "https://hostname:8443/hdp/login/saml/sso/test",
      "hdpUsernameIdentifier": "SAMLValidatedUser"
     }
    },
    "authTypeId": 4
}

OIDC example request

{
    "name": "OIDC",
    "tenantId": 23,
    "description": "OIDC Auth plugin",
    "authDefinition": {
     "issuerUrl": "https://login.microsoftonline.com/db26-4d26-ae1-d05535/v3.0",
     "hdpUsernameIdentifier": "test_username",  
       "attrValidation": {
         "type": "introspect",
         "introspectAuthMethod": "client_secret_post",
         "clientid": "2a9f8-3a06-984f-5a34e8f",
         "clientSecret": "ozQ~qZJjbcy4qkbL.5",
         "claimsToValidate": {
            "aud": "b17a9f23-0845-763-d890e9f1",
            "iss": "https://login.microsoftonline.com/da67-ae1a-d0585/v3.0",
         }
        }
    },
    "authTypeId": 5
}

Sample Response Payload

Java plugin example response

Status code: 201
Successful response
{
    "id": 43,
    "name": "jplugauth",
    "tenantId": 1,
    "description": "Java external auth plugin",
    "authDefinition": {
        "className": "com.test.hdp.plugins.auth.HDPUserAuthentication",
        "attributes": {
            "Server": "test-authentication",
            "BackupServer": "test-authentication-backup"
        }
    },
    "lastModifiedTime": "2018-02-15T11:09:35.107Z",
    "authTypeId": 2,
    "tenantName": "OrgM"
}

LDAP example response

Status code: 201
Successful response
{
    "id": 21,
    "name": "LDAP",
    "tenantId": 66,
    "description": "LDAP Auth plugin",
    "authDefinition": {
        "attributes": {
            "targetUrl": "LDAP://123.45.67.899:389",
            "securityAuthentication": "simple",
            "securityPrincipal": "CN=%LOGINNAME%,OU=TestRuns,DC=testdomain,DC=local"
        }
    },
    "lastModifiedTime": "2018-02-14T11:34:13.009Z",
    "authTypeId": 3,
    "tenantName": "OrgT"
}

SAML example response

Status code: 201
Successful response
{
  "id": 2,
  "name": "SAML",
  "tenantId": 1,
  "description": "SAML Auth plugin",
  "authDefinition": {
    "registrationId": "test",
    "assertingPartySSOUrl": "https://login.myserver.com/37d22137-b880-0247099d/saml",
    "assertingPartyEntityId": "https://sts.system.net/74b27217-b880-02470799266d/",
    "assertingPartyCertLoc": "Progress/DataDirect/Hybrid_Data_Pipeline/Hybrid_Server/ddcloud/keystore/",
    "relyingPartyEntityId": "https://hostname:8443/hdp/saml/service-metadata/test",
    "assertionConsumerServicePath": "https://hostname:8443/hdp/login/saml/sso/test",
    "hdpUsernameIdentifier": "SAMLValidatedUser"
    }
   },
    "lastModifiedTime": "2021-07-26T08:30:16.006Z",
    "authTypeId": 4,
    "tenantName": "OrgS"
}

OIDC example response

Status code: 201
Successful response
{
  "id": 5,
  "name": "OIDC",
  "tenantId": 23,
  "description": "OIDC Auth plugin",
  "authDefinition": {
    "issuerUrl": "https://login.microsoftonline.com/db26-4d26-ae1-d05535/v3.0",
    "hdpUsernameIdentifier": "test_username",  
       "attrValidation": {
         "type": "introspect",
         "introspectAuthMethod": "client_secret_post",
         "clientid": "2a9f8-3a06-984f-5a34e8f",
         "clientSecret": "ozQ~qZJjbcy4qkbL.5",
         "claimsToValidate": {
            "aud": "b17a9f23-0845-763-d890e9f1",
            "iss": "https://login.microsoftonline.com/da67-ae1a-d0585/v3.0",
         }
        }
    
   },
    "lastModifiedTime": "2021-09-26T08:30:16.006Z",
    "authTypeId": 5,
    "tenantName": "OrgO"
}

Sample Server Failure Response 

Status code: 400
Bad request, payload issues.

Authentication

Basic Authentication using Login ID and Password

Authorization

The user must have either the Administrator (12) permission, or the RegisterExternalAuthService (26) permission and administrative access to the tenant.