Modify a Custom Provider

Endpoint URL: /config/low/services/engage-v2 /apps/{appId}/custom-providers /{providerId}



Description

The PATCH method modifies an existing custom provider; for example, if an OpenID Connect provider changes its authorization URL or a SAML provider changes its X.509 certificate, you can use this method to update the corresponding identity provider.

Although there is only one PATCH method there are two ways to call this method when modifying a custom provider:

  • You can modify selected fields only. This is a “JSON merge” modification, in which the body parameter of your API call includes only the fields that need to be updated: any fields not included in the body parameter are left exactly as they are. For example, the following JSON snippet (body parameters must be formatted by using JSON) changes just the auth_url field for a social login identity provider
    {
        "auth_url": "https://documentation.akamai.com/saml/login"
    }
    An API call with this body parameter changes the provider’s auth_ui field value but leaves all other fields and field values untouched.

    This is the fastest, easiest, and most-common way to modify a custom provider.

  • You can replace all the fields in your provider with all the fields in your API call. In this type of modification (a “JSON patch” modification), all the existing fields and field values are deleted from the provider and replaced with the fields and field values specified in your body parameter. This has a number of implications, starting with this one: suppose your current OpenID Connect IdP includes the scopes field. That field might look something like this:
    "scopes": ["email","phone"]
    Let’s further suppose that you update the provider, but forget to include the scopes parameter in your API call. In that case, scopes will be removed from the updated provider. Why? That’s right: because all the existing fields and field values were removed from the provider and replaced with the fields defined in the API call. Because scopes weren’t defined in the API call, there was nothing to replace it with. This should give you a hint as to why the patch modification, while available, is used much less often than the merge modification.

    If you do use this option, it’s good practice to start by returning all the existing fields and field values for the custom provider and paste that data into your body parameter. You can then edit those fields and values as needed before making the actual API call.

As you might expect, having two update options means there are two different ways to configure your API call. To do a JSON merge modification (in which the body parameter includes only the fields that need to be updated), set the Content-Type header in your API call to application/merge-patch+json. For example, if you’re using Postman your header will look like this:

To do a JSON patch modification (in which the fields and field values in the body parameter replace all the existing fields and field values in the provider), set the Content-Type header of your API call to application/json-patch+json. For example:

If you make an API call that fails with a 415 Unsupported media type error, that typically means that you either used the wrong Content-Type header or that you forgot to include the Content-Type header.

There are at least two other points to consider when using the JSON merge method. For one, you can’t update a specific item within an object or an array. For example, suppose a provider’s attribute_map field looks like this:

"attribute_map": {
    "/email": "/emailAddress",
    "/givenName": "/first_name",
    "/familyName": "/last_name"
  }

Let’s further suppose that there’s a mistake in that mapping: the email attribute should actually be mapped to the IdP’s email_address attribute. With that in mind, you might use syntax like this to change this one value:

"attribute_map": {
    "/email": "/email_address"
  }

Unfortunately, that won’t result in the desired outcome. Instead, the provider’s entire attribute_map field will be replaced with the following:

"attribute_map": {
    "/email": "/email_address"
  }

If you need to make a change to a single item in an object or an array, you must include all the other items in that object or array as well. In other words:

"attribute_map": {
    "/email": "/email_address",
    "/givenName": "/first_name",
    "/familyName": "/last_name"
  }

And what if you want to remove a field? For example, token_auth_method is an optional field available to you when configuring an OpenID Connect or OAuth 2.0 provider. Suppose you originally included that field in your provider, but you now want to remove it. In a case like that, you can’t just omit the field from your API call; after all, with a JSON merge modification any fields not included in the body parameter are ignored (and thus not removed). Instead, you must include token_auth_method in your API call and set the value to null:

"token_auth_method": null

Important. For information about the fields that can (and cannot) be used when updating a custom provider, see the documentation for the /config/low/services/engage-v2/apps/{appId}/custom-providers endpoint and the POST method.


URL Parameters

URL parameters that must be included in the request are listed in the following table:

Parameter

Description

customerId

Unique identifier issued to Akamai customers. If you aren’t sure what your Akamai customer ID is, log on to Console and check the value of the customer_id application setting:

appId

Unique identifier of your Social Login application. You can return the IDs of all your Social Login applications by using the GET method and the /engage-v2/apps endpoint.

providerId

Unique identifier of the custom provider. IDs are assigned to a provider when the provider is created.


Authentication

This endpoint requires token-based authentication. To obtain an access token, you must use a configuration client (employing the client ID as the username and the client secret as the password) to access the /{customerId}/login/token endpoint. The access token returned from the token endpoint is then used in the Authorization header of your API call. 

For example, if you get back the access token z7S4iEe7KBRG8vMBPWRtJD66VH9SGMAlA56ol-loCln5MZOtGjmcy6O1tSh5lE6t your Authorization header will look like this when using Curl:

-H 'Authorization: Bearer z7S4iEe7KBRG8vMBPWRtJD66VH9SGMAlA56ol-loCln5MZOtGjmcy6O1tSh5lE6t'

If you’re using  Postman, set the Authorization Type to Bearer and use the access token as the value of the Token field:

Note. When requesting an access token, make sure you set the token scope to *:**. Any other scope will result in a 403 Forbidden error when you attempt to use the token.


Sample Request (curl)

The following command uses JSON merge to update the auth_url property (and only the auth_url property) for the custom provider with the ID d284e861-d7f9-426e-93b0-56e01cf6d0ea:

curl -L -X PATCH \
  'https://v1.api.us.janrain.com/3cc14467-fd4f-437d-a0c0-0b3888dd2ee4/v2/config/low/services/engage-v2/apps/fifbclhccfpjdeoejkag/custom-providers/d284e861-d7f9-426e-93b0-56e01cf6d0ea' \
  -H 'Content-Type: application/merge-patch+json' \
  -H 'Authorization: Bearer X4okxl37_XecQ-jklmr7Z_foiZiB3_iPXe5QW9jygTWZ4Hw8G7aFDUsqgwwuSoTt' \
  --data-raw '{"auth_url": "https://dev-71752379.akamai.com/home/generic-saml/0oabsqs0dVxusS8ai5d6/1919"}'


Responses

204 No Content

If your API call succeeds you will not get back a detailed API response. However, you will get back the HTTP status code 204 No Content, which indicates that the provider was successfully updated.


Error Response Codes

The following table includes information about some of the other response codes that you might encounter when calling this endpoint.

Response Code

Description

400

The request was invalid. Typically occurs in one of two instances:

  • Your URL is incorrect. Verify each section of the URL and then try again.
  • Your body parameter has been configured incorrectly. This is often because the JSON formatting isn’t valid.

403

Forbidden. Access is denied. This typically occurs because your configuration access token has expired. Obtain a new access token and then try again.

404

The requested resource was not found. Typically occurs if your call specifies an invalid customer ID, application ID, or provider ID. Verify that those values are correct and then try again.

415

Unsupported media type. Typically occurs if the Content-Type header is not configured correctly. The Content-Type header must be set to one of the following two values:

  • application/merge-patch+json if your API call only updates the fields specified in the body parameter.
  • application/json-patch+json if your API call replaces all the existing fields in the provider with the fields specified in the body parameter.

422

Update failed. Typically occurs if your body parameter specifies a field that can’t be found in the provider being updated. This might occur because:

  • You misspelled a field name (protcol) or used incorrect letter casing in a field name (auth_URL).
  • You referenced a SAML-only field (e.g., idp_certificate) for an OpenID Connect or OAuth provider (or vice-versa).