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 (the easiest and most-commonly employed method)
• 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 body parameter 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 body parameter 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 body parameter:

{
    "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 body parameter 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:

With JSON Patch, you must specify all the required properties and property values in the body parameter of your API call, and must do so even if the majority of those property values aren’t being changed. That’s because JSON Patch works by first removing all the existing properties and property values from the provider, then replacing those properties and property values with whatever happens to be in the body parameter. For example, suppose your identity provider’s authorization server URL has changed and, as a result, you need to update the auth_url property for your custom provider. To do that, you set your body parameter to the following (after setting your Content-Type header to application/json-patch+json, of course):

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

This API call is going to fail. Why? That’s easy: after all, an OAuth/OIDC provider has a number of required properties (protocol, token_url, profile_url, etc.) that aren’t included in the body parameter. If even one of those required properties is missing the API call fails. Your API call must include all the required properties and property values as well as all the optional properties and property values you want your provider to have.

👍

One way to help ensure that you don’t forget to include a property? Before you modify the provider, use the GET method to return that provider’s existing properties and property values. Copy the returned data, paste it into your body parameter, and then start making your changes.

Another thing to watch out for is this. Some provider properties (such as attribute_map) are optional: for example, you can have a custom provider that doesn’t include the attribute_map property. Why do we mention this? Well, suppose your provider currently has an attribute map, and you need to make a change to that provider. In the body parameter of your API call you include all the required properties, but you inadvertently leave out the attribute_map property. When you make your API call, the attribute_map (and any other optional properties you failed to include in the body parameter) will be deleted from the provider. Your API call will work, but maybe not in the way you intended it to.

Which is exactly why JSON Patch is used much less-frequently than JSON Merge.