Purpose

Retrieve information on an authentication service.

URL

https://<myserver>:<port>/api/admin/auth/services/{id}

Method

GET

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.

The URL parameter {id} is required.

Property Description Valid Values
{id} The ID of the authentication service. The automatically generated external authentication service ID.

Response Definition

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

Response 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",
       ...
    },
    "lastModifiedTime": "timestamp",
    "authTypeId": authtype_id,
    "tenantName": tenant_name
}
Property Description Valid Values
"name" The name of the authentication service. A string that provides a name for the authentication service.
"tenantId" The ID of the tenant. A valid tenant ID.
"description" The description of the authentication service. A string that provides a description for the authentication service.
"authDefinition" An object that defines the authentication service. 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.
"lastModifiedTime" The date and time the service was last modified. A complete datetime with timezone string.
"authTypeId" The ID of the authentication type. 2 must be specified for a Java plugin service.
"tenantName" The name of the tenant. A string that specifies the name of the tenant.

Response definition for LDAP service

{
    "id": authservice_id,
    "name": "authservice_name",
    "tenantId": tenant_id,
    "description": "authservice_description",
    "authDefinition": {
        "attributes": {
            "targetUrl": "LDAP_URL",
            "securityAuthentication": "LDAP_auth_mechanism",
            "securityPrincipal": "LDAP_principal",
            "securityCredentials": "LDAP_credentials"
        }
    },
    "lastModifiedTime": "timestamp",
    "authTypeId": authtype_id,
    "tenantName": tenant_name
}
Property Description Valid Values
"name" The name of the authentication service. A string that provides a name for the authentication service.
"tenantId" The ID of the tenant. A valid tenant ID.
"description" The description of the authentication service. A string that provides a description for the authentication service.
"authDefinition" An object that defines the authentication service. For an LDAP service, the following attributes must be specified via the attributes object.
  • targetUrl
  • securityAuthentication
  • securityPrincipal
  • securityCredentials (optional)

See authDefinition Object for details.
"lastModifiedTime" The date and time the service was last modified. A complete datetime with timezone string.
"authTypeId" The ID of the authentication type. 3 must be specified for an LDAP service.
"tenantName" The name of the tenant. A string that specifies the name of the tenant.

Response definition for SAML service

{
    "id": authservice_id,
    "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"
        }
    },
    "lastModifiedTime": "timestamp",
    "authTypeId": authtype_id,
    "tenantName": tenant_name
}
Property Description Valid Values
"name" The name of the authentication service. A string that provides a name for the authentication service.
"tenantId" The ID of the tenant. A valid tenant ID.
"description" The description of the authentication service. A string that provides a description for the authentication service.
"authDefinition" An object that defines the authentication service. 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.
"lastModifiedTime" The date and time the service was last modified. A complete datetime with timezone string.
"authTypeId" The ID of the authentication type. 4 must be specified for a SAML service.
"tenantName" The name of the tenant. A string that specifies the name of the tenant.

Response definition for OIDC service

{
    "id": authservice_id,
    "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",
           "clientSecret": "client_secret",
           "claimsToValidate": "A JSON object containing the claims in key-value pairs",
           "otherAttributes": "Optional. A JSON object with key and value pairs"
         }
    },
    "lastModifiedTime": "timestamp",
    "authTypeId": authtype_id,
    "tenantName": "tenant_name"
}
Property Description Valid Values
"name" The name of the authentication service. A string that provides a name for the authentication service.
"tenantId" The ID of the tenant. A valid tenant ID.
"description" The description of the authentication service. A string that provides a description for the authentication service.
"authDefinition" An object that defines the authentication service.

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.
"lastModifiedTime" The date and time the service was last modified. A complete datetime with timezone string.
"authTypeId" The ID of the authentication type. 5 must be specified for a OIDC service.
"tenantName" The name of the tenant. A string that specifies the name of the tenant.

Sample Response Payload

Java plugin example response

Status code: 200
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: 200
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: 200
Successful response
{
  "id": 2,
  "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"
     }
    },
    "lastModifiedTime": "2021-07-26T08:30:16.006Z",
    "authTypeId": 4,
    "tenantName": "OrgS"
}

OIDC example response

Status code: 200
Successful response
{
  "id": 3,
  "name": "OIDC",
  "tenantId": 1,
  "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-36T08:30:16.006Z",
    "authTypeId": 5,
    "tenantName": "OrgO"
}

Sample Server Failure Response 

Status code: 404
Supplied Services ID not found.

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.