Guide

Modify a custom provider

Suggest Edits

If you need to make changes to a custom provider you can do so by using the PATCH method and the /custom-providers/{providerId} operation. However, before you start modifying your providers you need to know that there are actually two ways you can modify a custom provider (although both approaches use the PATCH method). To be more specific, you can choose between:

  • A JSON merge patch update
  • A JSON patch update

In the next two sections, we’ll explain what it means to use each of these approaches.


JSON merge patch


📘

To use the JSON Merge Patch, you must set the Content-Type header in your API call to application/merge-patch+json. For example, if you’re using Postman your header needs to look like this:


If you use JSON Patch Merge, that means that your request body only has to include the properties and property values being updated: you don’t have to include all the properties and property values of the provider in your API call. 

📘

Yes, that differs from many Identity Cloud API operations, most of which rely on the PUT method when modifying objects.


For example, suppose your identity provider’s login page has changed and, as a result, you need to update the value of the auth_url property in your custom provider. In that case, your JSON-formatted request body only needs to include the auth_url property:

{
    "auth_url": "https://idp.example.com/authorize/login"
}

What if you need to change two property values? Then include both of those values in the request body:

{
    "auth_url": "https://idp.example.com/authorize/login",
    "scopes": ["openid","email"]
}

That’s all you have to do. A complete Curl command for modifying a custom identity provider (in this example, a command that modifies only the ui property) will look similar to this:

curl -L -X PATCH \
  'https://v1.api.or-stg.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 4kcWwH40pIf3v8gWvA-
  --data-raw '{
    "ui": {
        "title": "Okta SAML",
        "icon_url": "https://www.okta.com/sites/default/files/Dev_Logo-02_Large-thumbnail.png"
    }
}'

If this API call succeeds, you won’t get back a complete API response (i.e., one that lists all the properties and property values). However, you will get back the HTTP status code 204 No Content.

There are a couple other things to be aware of when using the JSON merge method to update a provider. First, 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": "/email",
    "/name/givenName": "/given_name",
    "/name/familyName": "/family_name"
  }

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

"attribute_map": {
    "/email": "/emailAddress"
  }

Your API call will run, but it won’t have the hoped-for outcome. Instead, the provider’s attribute_map field will be replaced with the following

attribute_map": {
    "/email": "/emailAddress"
  }

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": "/emailAddress",
    "/name/givenName": "/given_name",
    "/name/familyName": "/family_name"
  }

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

"token_auth_method": null

Because you change a single property (and without having to include all the other properties and property values in your API call), JSON Merge will almost-always be the easiest, fastest, and least error-prone way to modify a custom provider.


JSON patch


📘

To use JSON patch to modify a provider you must set the Content-Type header in your API call to application/json-patch+json. For example, in Postman your header will look like this:


Another way to update a custom provider is to use JSON patch. With this method, you start by setting your Content-Type header to application/json-patch+json, then use a JSON-formatted request body similar to this:

[
  {
    "op": "replace",
    "path": "/title",
    "value": "Akamai OIDC Provider Version II"
  }
]

In the preceding example, op indicates the type of operation you’re carrying out (the Custom Provider only supports the replace and the test operations). As the name implies, the replace operation replaces an existing value with a new value. In this case, we’re replacing the title of our custom provider with the new value Akamai OIDC Provider Version II. Two things to note here:

  • path specifies the field we’re updating.
  • The field name must be prefaced with a /. The correct field name is /title, not title.

Along similar lines, make sure that the value is formatted properly. In the preceding example, title is correctly formatted as a string. However, the idp_certificate_chain member used with SAML2 providers must be formatted as a JSON array. Suppose you don’t format this value as an array:

"value": "j8d8QuHfHEBH9QGVgROeddVR1RsboOY5gi36x/x … 6wui3pfak229I="

In that case, your API call fails with an error similar to this:

{
  "type": "/identity-cloud/error-types/invalid-request-field",
  "status": 400,
  "title": "Invalid request field",
  "instance": "/idp_certificate_chain",
  "detail": "Field /idp_certificate_chain must be an array of string",
  "suggestion": "Send this field with valid data"
}

Instead, format the value as a JSON array :

"value": ["j8d8QuHfHEBH9QGVgROeddVR1RsboOY5gi36x/x … 6wui3pfak229I="]

In addition to changing the value of an existing field, you can also use replace to add and delete fields. For example, suppose you have a SAML2 provider that doesn’t include the optional X.509 certificate chain (idp_certificate_chain). If you want to add an X.509 chain to that provider use a request body similar to this:

[
  {
    "op": "replace",
    "path": "/idp_certificate_chain",
    "value": ["j8d8QuHfHEBH9QGVgROeddVR1RsboOY5gi36x/x … 6wui3pfak229I="]
   }
]

In this example, the custom provider doesn’t have an existing certificate chain. However, the preceding request adds the missing field (idp_certificate_chain) and sets the value accordingly. If a field already exists, replace updates the value of that field. If a field doesn’t exist, replace creates the field and then sets the value.

Similarly, suppose you want to delete an existing field. For example, you now want to remove the certificate chain. To do that, use the replace method but set the value to null:

[
  {
    "op": "replace",
    "path": "/idp_certificate_chain",
    "value": null
   }
]

That deletes idp_certificate_chain.

We should also note that you can modify multiple items in a single API call. To do that, just be sure to have a separate JSON block for each value being updated. For example, in this request body both the title and the auth_url fields are modified:

[
  {
    "op": "replace",
    "path": "/title",
    "value": "Akamai SAML2 Provider"
   },
   {
     "op": "replace",
     "path": "/auth_url",
     "value": "https://akamai-technologies---assets-46464.login.go.akamai-access.com/saml/idp/sso2"
   }
]

Finally, and similar to JSON merge patch, you can’t modify individual elements within an array. For example suppose you have an attribute map similar to this one:

{
   "/displayName": "/display_name",
    "/email": "/email",
    "/familyName": "/family_name",
    "/givenName": "/given_name",
    "/verifiedEmail": "/email_verified"
}

If you want to remove /verifiedEmail, you can’t use a remove operation to delete that one element. Instead, you have to replace the existing value of attribute_map with a new value that doesn’t include /verifiedEmail:

[
  {
    "op": "replace",
    "path": "/attribute_map",
    "value": {
   "/displayName": "/display_name",
    "/email": "/email",
    "/familyName": "/family_name",
    "/givenName": "/given_name"
  }
   }
]

To restore verifiedEmail take a similar approach:

[
  {
    "op": "replace",
    "path": "/attribute_map",
    "value": {
   "/displayName": "/display_name",
    "/email": "/email",
    "/familyName": "/family_name",
    "/givenName": "/given_name",
    "/verifiedEmail": "/email_verified"
  }
   }
]

That’s because Identity Cloud doesn’t support the add operation.

A quick note regarding the test operation

In addition to replace, the Custom Provider API also supports the test operation. This operation enables you to verify a specified value. For example, suppose you want to know if the title of your SAML2 provider is Akamai SAML2 Provider. In that case, use this request body:

[
  {
    "op": "test",
    "path": "/title",
    "value": "Akamai SAML2 Provider"
   }
]

If the custom provider title really is Akamai SAML2 Provider you’ll get back the HTTP status code 204 No Content. If that isn’t the title, then you’ll get back an error similar to this:

{
  "type": "/identity-cloud/error-types/test-operation-failed",
  "status": 409,
  "title": "Test operation failed",
  "instance": "/title",
  "detail": "Field /title was not equal to \"Akamai SAML2 Provider\""
}

Updated almost 3 years ago