Skip to main content

Update a federation

PATCH /organizations/{organization_id}/federations/{federation_id}

Updates the specified federation.

Parameters

Name Type In Required Description

organization_id

string

path

True

Identifier for an organization.

federation_id

string

path

True

ID of the federation.

  • example: 645eae30-ea32-4542-af58-1d9012fed81a

Request Body

Replaces the specified attributes in the request body with the values provided.

Name Type Required Description

adfsOptions

federation_1.0_adfs_request_options

False

Active Directory Federation Services (AD FS) configuration options when providerType=ADFS. Either metadataUrl or metadataFile must be provided.

domains

array[string]

False

Array of email domain names that are associated with the federation.

All previously configured domains must be included in the request body when updating the domains field or they will be removed. Previously configured domains do not need to be in a VERIFIED state.

If a domain matches the user's email address or is an Entra ID *.onmicrosoft.com tenant domain, then it does not need to be in a VERIFIED state. All other domains must be added to the domains collection and in a VERIFIED state.

entraIdOptions

federation_1.0_entraid_patch_request_options

False

Microsoft Entra ID (formerly Azure Active Directory) configuration options when providerType=ENTRAID.

expirationNotificationPeriod

string

False

The time period when expiration notifications are generated. Defined values are:

  • "P7D" - Notifications are sent daily 7 days before expiration.

  • "P30D" - Notifications are sent weekly 30 days before expiration. Notifications are sent daily 7 days before expiration.

expirationTimestamp

string

False

The date that the credentials expire. This is only applicable when providerType=ENTRAID. When a certificate is provided for other provider types, the value is set to the certificate's expiration timestamp.

name

string

False

The name of the federation.

pingFederateOptions

federation_1.0_pingfederate_patch_request_options

False

PingFederate configuration options when providerType=PINGFEDERATE.

providerType

string

False

The type of the identity provider. Defined values are:

  • "ADFS" - Active Directory Federation Services

  • "ENTRAID" - Microsoft Entra ID (formerly Azure Active Directory)

  • "PINGFEDERATE" - PingFederate

  • "SAML" - Security Assertion Markup Language 2.0

samlOptions

federation_1.0_saml_patch_request_options

False

SAML configuration options when providerType=SAML.

stateDesired

string

False

The desired state of the federation. Defined values are:

  • "DRAFT" - The federation is partially configured.

  • "CREATED" - The federation is configured but not tested.

  • "TESTED" - The federation has been successfully tested.

  • "ENABLED" - The federation is enabled.

  • "DISABLED" - The federation is disabled.

type

string

True

Media type of the resource.

version

string

True

Version of the resource.
Example request 
{
  "adfsOptions": {
    "metadataFile": "<?xml version=\"1.0\"?>\n<EntityDescriptor xmlns=\"urn:oasis:names:tc:SAML:2.0:metadata\"...",
    "metadataUrl": "https://example.com/FederationMetadata/2007-06/FederationMetadata.xml"
  },
  "domains": [
    "example.com",
    "example2.com"
  ],
  "entraIdOptions": {
    "clientId": "94e2a45c-64e6-48d1-a31e-1eee0ded5c2a",
    "clientSecret": "qPz:*1SAcqLjpP=QzMeeHD=[mWcF5u",
    "tenantDomain": "example.onmicrosoft.com"
  },
  "expirationNotificationPeriod": "P30D",
  "expirationTimestamp": "2024-11-18T20:58:16.305662Z",
  "name": "Example Co.",
  "pingFederateOptions": {
    "serverUrl": "https://example.com/saml/signin",
    "signingCertificate": "-----BEGIN CERTIFICATE-----\nMIIC+jCCAeKgAwIBAgIJM..."
  },
  "providerType": "ENTRAID",
  "samlOptions": {
    "signInUrl": "https://example.com/saml/signin",
    "signOutUrl": "https://example.com/saml/signout",
    "signingCertificate": "-----BEGIN CERTIFICATE-----\nMIIC+jCCAeKgAwIBAgIJM..."
  },
  "stateDesired": "ENABLED",
  "type": "application/vnd.netapp.bxp.federation",
  "version": "1.0"
}

Response

Status: 200, Returns the updated federation in the JSON response body.
Name Type Required Description

adfsOptions

federation_1.0_adfs_response_options

False

Active Directory Federation Services (AD FS) configuration options when providerType=ADFS.

auth0Id

string

False

The ID of the connection in Auth0.

auth0Name

string

False

The name of the connection in Auth0.

domains

array[string]

False

Array of email domain names that are associated with the federation.

entraIdOptions

federation_1.0_entraid_response_options

False

Microsoft Entra ID (formerly Azure Active Directory) configuration options when providerType=ENTRAID.

expirationNotificationPeriod

string

False

The time period when expiration notifications are generated. Defined values are:

  • "P7D" - Notifications are sent daily 7 days before expiration.

  • "P30D" - Notifications are sent weekly 30 days before expiration. Notifications are sent daily 7 days before expiration.

expirationTimestamp

string

False

The date that the credentials or certificate expires. When a certificate is provided, the value is set to the certificate's expiration timestamp.

id

string

False

Globally unique identifier of the resource conforming to the UUIDv4 schema.

metadata

type_bxp_metadata

False

Metadata associated with the resource.

name

string

False

The name of the federation.

organizationId

string

False

Identifier for an organization.

pingFederateOptions

federation_1.0_pingfederate_response_options

False

PingFederate configuration options when providerType=PINGFEDERATE.

providerType

string

False

The type of the identity provider. Defined values are:

  • "ADFS" - Active Directory Federation Services

  • "ENTRAID" - Microsoft Entra ID (formerly Azure Active Directory)

  • "PINGFEDERATE" - PingFederate

  • "SAML" - Security Assertion Markup Language 2.0

resourceId

string

False

Identifier for the resource.

samlOptions

federation_1.0_saml_response_options

False

SAML configuration options when providerType=SAML.

state

string

False

The state of the federation. Defined values are:

  • "DRAFT" - The federation is partially configured.

  • "CREATED" - The federation is configured but not tested.

  • "TESTED" - The federation has been successfully tested.

  • "ENABLED" - The federation is enabled.

  • "DISABLED" - The federation is disabled.

type

string

False

Media type of the resource.

version

string

False

Version of the resource.
Example response 
{
  "adfsOptions": {
    "metadataUrl": "https://example.com/FederationMetadata/2007-06/FederationMetadata.xml",
    "signingCertificateFingerprint": "33:0E:66:6A:D0:89:EA:78:10:7D:5A:35:FF:C5:51:E9:3A:CB:47:A8"
  },
  "auth0Id": "con_jxQFVfPHKSdiwoxs",
  "auth0Name": "fed-example-com-waad",
  "domains": [
    "example.com",
    "example2.com"
  ],
  "entraIdOptions": {
    "clientId": "94e2a45c-64e6-48d1-a31e-1eee0ded5c2a",
    "clientSecretMasked": "qPz*******",
    "tenantDomain": "example.onmicrosoft.com"
  },
  "expirationNotificationPeriod": "P30D",
  "expirationTimestamp": "2024-11-18T20:58:16.305662Z",
  "id": "4336388b-2992-43af-81de-ba9284b7dc36",
  "metadata": {
    "createdBy": "666a3f38-d4fa-5b62-a391-a69029758d32",
    "creationTimestamp": "2022-10-06T20:58:16.305662Z",
    "labels": [
      {
        "name": "string",
        "value": "string"
      }
    ],
    "modificationTimestamp": "2022-10-06T20:58:16.305662Z",
    "modifiedBy": "666a3f38-d4fa-5b62-a391-a69029758d32"
  },
  "name": "Example Co.",
  "organizationId": "9b0ee210-70a0-4158-b025-0decde66e4de",
  "pingFederateOptions": {
    "serverUrl": "https://example.com/saml/signin",
    "signingCertificateFingerprint": "33:0E:66:6A:D0:89:EA:78:10:7D:5A:35:FF:C5:51:E9:3A:CB:47:A8"
  },
  "providerType": "ENTRAID",
  "resourceId": "862b6f03-58ac-479b-9ca5-5cb4429d8996",
  "samlOptions": {
    "signInUrl": "https://example.com/saml/signin",
    "signOutUrl": "https://example.com/saml/signout",
    "signingCertificateFingerprint": "33:0E:66:6A:D0:89:EA:78:10:7D:5A:35:FF:C5:51:E9:3A:CB:47:A8"
  },
  "state": "ENABLED",
  "type": "application/vnd.netapp.bxp.federation",
  "version": "1.0"
}

Error

Status: 400, Bad request
Name Type Required Description

correlationId

string

False

Internal UUID representing the request or trace ID related.

detail

string

False

Details about the problem.

invalidParams

array[invalidParams]

False

List of invalid parameters.

status

string

True

HTTP error code related to the problem.

title

string

True

Title description of the problem.

type

string

True

Content-type of the object.
Example error response 
{
  "detail": "The supplied query parameters are invalid.",
  "status": "400",
  "title": "Invalid query parameters",
  "type": "https://bluexp.netapp.io/problems/1"
}

Error

Status: 401, Unauthorized
Name Type Required Description

correlationId

string

False

Internal UUID representing the request or trace ID related.

detail

string

False

Details about the problem.

invalidParams

array[invalidParams]

False

List of invalid parameters.

status

string

True

HTTP error code related to the problem.

title

string

True

Title description of the problem.

type

string

True

Content-type of the object.
Example error response 
{
  "detail": "The request is missing the required bearer token.",
  "status": "401",
  "title": "Missing bearer token",
  "type": "https://bluexp.netapp.io/problems/1"
}

Error

Status: 403, Forbidden
Name Type Required Description

correlationId

string

False

Internal UUID representing the request or trace ID related.

detail

string

False

Details about the problem.

invalidParams

array[invalidParams]

False

List of invalid parameters.

status

string

True

HTTP error code related to the problem.

title

string

True

Title description of the problem.

type

string

True

Content-type of the object.
Example error response 
{
  "detail": "The requested operation isn't permitted.",
  "status": "403",
  "title": "Operation not permitted",
  "type": "https://bluexp.netapp.io/problems/11"
}

Error

Status: 404, Not found
Name Type Required Description

correlationId

string

False

Internal UUID representing the request or trace ID related.

detail

string

False

Details about the problem.

invalidParams

array[invalidParams]

False

List of invalid parameters.

status

string

True

HTTP error code related to the problem.

title

string

True

Title description of the problem.

type

string

True

Content-type of the object.
Example error response 
{
  "detail": "The collection specified in the request URI wasn't found.",
  "status": "404",
  "title": "Collection not found",
  "type": "https://bluexp.netapp.io/problems/2"
}

Definitions

See Definitions

federation_1.0_adfs_request_options

Active Directory Federation Services (AD FS) configuration options when providerType=ADFS. Either metadataUrl or metadataFile must be provided.

Name Type Required Description

metadataFile

string

False

JSON escaped contents of the Federation metadata XML file.

metadataUrl

string

False

AD FS server URL for the Federation metadata XML file.

federation_1.0_entraid_patch_request_options

Microsoft Entra ID (formerly Azure Active Directory) configuration options when providerType=ENTRAID.

Name Type Required Description

clientId

string

False

Entra ID client ID.

clientSecret

string

False

Entra ID client secret.

tenantDomain

string

False

Entra ID domain.

federation_1.0_pingfederate_patch_request_options

PingFederate configuration options when providerType=PINGFEDERATE.

Name Type Required Description

serverUrl

string

False

PingFederate server URL.

signingCertificate

string

False

X.509 Signing certificate in PEM or CER format converted to a string with escaped new-line characters (\n).

federation_1.0_saml_patch_request_options

SAML configuration options when providerType=SAML.

Name Type Required Description

signInUrl

string

False

SAML single login URL.

signOutUrl

string

False

SAML single logout URL.

signingCertificate

string

False

X.509 signing certificate in PEM or CER format converted to a string with escaped new-line characters (\n).

federation_1.0_adfs_response_options

Active Directory Federation Services (AD FS) configuration options when providerType=ADFS.

Name Type Required Description

metadataUrl

string

False

AD FS server URL for the Federation metadata XML file.

signingCertificateFingerprint

string

False

The SHA-1 fingerprint of the X.509 signing certificate if the metadata XML file was provided.

federation_1.0_entraid_response_options

Microsoft Entra ID (formerly Azure Active Directory) configuration options when providerType=ENTRAID.

Name Type Required Description

clientId

string

False

Entra ID client ID.

clientSecretMasked

string

False

Partially masked Entra ID client secret.

tenantDomain

string

False

Entra ID domain.

type_bxp_label

Name/value pair.

Name Type Required Description

name

string

True

Name of the label.

value

string

True

Value of the label.

type_bxp_metadata

Metadata associated with the resource.

Name Type Required Description

createdBy

string

False

UUID of the user who created the resource.

creationTimestamp

string

False

Resource creation date.

labels

array[type_bxp_label]

False

Array of name/value pairs representing additional information for the resource.

modificationTimestamp

string

False

Resource modification date.

modifiedBy

string

False

UUID of the user who modified the resource.

federation_1.0_pingfederate_response_options

PingFederate configuration options when providerType=PINGFEDERATE.

Name Type Required Description

serverUrl

string

False

PingFederate server URL.

signingCertificateFingerprint

string

False

The SHA-1 fingerprint of the X.509 Signing certificate.

federation_1.0_saml_response_options

SAML configuration options when providerType=SAML.

Name Type Required Description

signInUrl

string

False

SAML single login URL.

signOutUrl

string

False

SAML single logout URL.

signingCertificateFingerprint

string

False

The SHA-1 fingerprint of the X.509 Signing certificate.

invalidParams

Name Type Required Description

name

string

True

Name of the invalid parameter.

reason

string

True

Reason why the parameter is invalid.