Purpose

Updates an authentication service. The internal authentication service cannot be modified.

URL

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

Method

PUT

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.

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",
    "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.
"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",
    "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.
"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 a 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 registrationId, 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 a SAML service.

Request definition for OIDC service

{
 "name": "authservice_name",
 "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"
         }
    },
    "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.
"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 a OIDC service.

Sample Request Payload

Java plugin example request

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

LDAP example request

{
    "name": "LDAP",
    "tenantId": 66,
    "description": "LDAP Auth plugin",
    "authDefinition": {
        "attributes": {
            "targetUrl": "LDAP://987.65.43.211:389",
            "securityAuthentication": "simple",
            "securityPrincipal": "CN=%LOGINNAME%,OU=ProdRuns,DC=proddomain,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: 200
Successful response
{
    "id": 43,
    "name": "jplugauth",
    "tenantId": 1,
    "description": "Java external auth plugin",
    "authDefinition": {
        "className": "com.prod.hdp.plugins.auth.HDPUserAuthentication",
        "attributes": {
            "Server": "prod-authentication",
            "BackupServer": "prod-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://987.65.43.211:389",
            "securityAuthentication": "simple",
            "securityPrincipal": "CN=%LOGINNAME%,OU=ProdRuns,DC=proddomain,DC=local"
        }
    },
    "lastModifiedTime": "2018-02-14T11:34:13.009Z",
    "authTypeId": 3,
    "tenantName": "OrgT"
}

SAML example response

Status code: 200
Successful response
{
  "id": 4,
  "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-14T11:34:13.009Z",
    "authTypeId": 4,
    "tenantName": "OrgS"
}

OIDC example response

Status code: 200
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-14T11:44:13.009Z",
    "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.