Modify a custom provider
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.
Updated 44 minutes ago