> For AI agents: [llms.txt](https://docs.trustedauth.com/llms.txt) provides a Markdown index of this documentation. # Get a SAML identity provider `GET /api/web/v1/identityproviders/saml/{id}` Get a SAML identity provider. Caller requires the IDENTITYPROVIDERS:VIEW permission. ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | id | path | Yes | string | The UUID of the SAML Identity Provider to get. | ## Responses ### 200 Successful #### application/json Schema ```json { "type": "object", "properties": { "acrValues": { "type": "string", "description": "The space separated list of authentication context request values to request as part of the external SAML identity provider user authentication or user verification request.", "example": "level1 level2" }, "acsUrl": { "type": "string", "description": "The assertion consumer service URL provided to the external SAML identity provider. Leave empty to use default value.", "example": "https://test.us.trustedauth.com/api/saml/SAML2/ACS" }, "authenticationEnabled": { "type": "boolean", "description": "A flag indicating if the external SAML identity provider can be used for user authentication.", "example": true }, "buttonImage": { "type": "string", "description": "The URI of the logo to display on the login button for this external SAML identity provider.", "example": "https://account.mycompany.com/images/logo.png" }, "buttonText": { "type": "string", "description": "The unique text to display on the login button for this external SAML identity provider.", "example": "Sign in With MyCompany Co." }, "createUser": { "type": "boolean", "description": "A flag indicating if the user should be created after authenticating to the external SAML identity provider if it doesn't exist. The user attributes specified by the userAttributeMappings attribute are used to populate the user in IDaaS. This value is used if authenticationEnabled is true.", "example": true }, "defaultProvider": { "type": "boolean", "description": "A flag indicating if this is the tenant's default identity provider. This value applies only to non-domain based identity providers. Only one identity provider can be set as the default at a time." }, "domains": { "type": "string", "description": "The space separated list of domains associated with the external SAML identity provider for use with user authentication.", "example": "test.com sample.com" }, "externalGroupMappings": { "type": "array", "description": "The association between a group claim returned from the external SAML identity provider and authorization groups. This mapping is used to associate SAML identity provider external groups when a user is created or modified based on user authentication or when it is modified based on an external SAML identity provider user verification. This value can only be set if createUser, updateUser, or updateVerificationUser is true and groupMapping is present.", "items": { "required": [ "externalGroupId", "groupId" ], "type": "object", "properties": { "externalGroupId": { "type": "string", "description": "The external group name/ID returned from the identity provider.", "example": "admin-group" }, "groupId": { "type": "string", "description": "The Authorization Group UUID this external group maps to." }, "id": { "type": "string", "description": "The UUID of the identity provider external group mapping. This value is generated once the mapping is created.", "example": "6781549d-433c-44ea-a42f-4705c26f3245" }, "identityProviderId": { "type": "string", "description": "The ID of the identity provider this external group mapping belongs to.", "example": "6781549d-433c-44ea-a42f-4705c26f3245" } }, "description": "A IdentityProviderExternalGroupMapping maps a group name/ID returned from an external identity provider to an Authorization Group for matching purposes.", "title": "IdentityProviderExternalGroupMapping" } }, "forceAuthn": { "type": "boolean", "description": "A flag indicating if a force authentication should always be requested as part of the external SAML identity provider user authentication or user verification request.", "example": false }, "groupIds": { "type": "array", "description": "The UUIDs of groups that will be assigned to users created after an external SAML identity provider user authentication. An empty list means the user will be assigned to All Groups. If configured, the full set of groups must be configured. This value is used if createUser is true.", "items": { "type": "string", "description": "The UUIDs of groups that will be assigned to users created after an external SAML identity provider user authentication. An empty list means the user will be assigned to All Groups. If configured, the full set of groups must be configured. This value is used if createUser is true." } }, "groupMapping": { "type": "string", "description": "The association between a specified claim returned from the external SAML identity provider and IDaaS groups. This mapping is used to associated IDaaS groups when a user is created or modified based on an external SAML identity provider user authentication or when it is modified based on an external SAML identity provider user verification. This value is used if createUser, updateUser, or updateVerificationUser is true." }, "id": { "type": "string", "description": "The UUID of the external SAML identity provider.", "example": "6784549d-433c-44ea-a42f-4701458dg245" }, "issuer": { "type": "string", "description": "The issuer, or IDP Entity ID, for the external SAML identity provider.", "example": "https://accounts.mycompany.com" }, "name": { "type": "string", "description": "The unique name of the external SAML identity provider.", "example": "MyCompany Co." }, "nameIdPolicyFormat": { "type": "string", "description": "The name ID policy format to request as part of the external OIDC identity provider user authentication or user verification request.", "example": "urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress" }, "organizationIds": { "type": "array", "description": "The UUIDs of organizations that will be assigned to users created after an external SAML identity provider user authentication. If configured, the full set of organizations must be configured. This value is used if createUser is true.", "items": { "type": "string", "description": "The UUIDs of organizations that will be assigned to users created after an external SAML identity provider user authentication. If configured, the full set of organizations must be configured. This value is used if createUser is true." } }, "requireAssertionSignature": { "type": "boolean", "description": "A flag indicating if the SAML Assertion of the external SAML identity provider should be signed and verified.", "example": true }, "requireResponseSignature": { "type": "boolean", "description": "A flag indicating if the SAML Response of the external SAML identity provider should be signed and verified.", "example": true }, "roleId": { "type": "string", "description": "The UUID of the role that will be assigned to users created after an external SAML identity provider user authentication. An empty string means the user will not be assigned a role by default. This role acts as the default if role mapping is empty. This value can only be set if createUser is true." }, "roleMapping": { "type": "string", "description": "The association between a specified claim returned from the external SAML identity provider and an IDaaS role. This mapping is used to associated an IDaaS role when a user is created or modified based on an external SAML identity provider user authentication or when it is modified based on an external SAML identity provider user verification. This value is used if createUser, updateUser, or updateVerificationUser is true." }, "sloEndpoint": { "type": "string", "description": "The single logout endpoint for the external SAML identity provider.", "example": "https://account.mycompany.com/saml/slo" }, "spEntityId": { "type": "string", "description": "The SP entity ID provided to the external SAML identity provider.", "example": "client123" }, "ssoEndpoint": { "type": "string", "description": "The single signon endpoint for the external SAML identity provider.", "example": "https://account.mycompany.com/saml/sso" }, "type": { "type": "string", "description": "The type of the external SAML identity provider. Once created, this value cannot be updated.", "example": "GENERIC", "enum": [ "GENERIC" ] }, "updateUser": { "type": "boolean", "description": "A flag indicating if the user should be updated after authenticating to the external SAML identity provider if it exists. The user attributes specified by the userAttributeMappings attribute are used to populate the user in IDaaS. This value is used if authenticationEnabled is true.", "example": true }, "updateUserVerification": { "type": "boolean", "description": "A flag indicating if the user should be updated after user verification to the external SAML identity provider if it exists. The user attributes specified by the userAttributeMappings attribute are used to populate the user in IDaaS. This value is used if verificationEnabled is true.", "example": true }, "userAttributeId": { "type": "string", "description": "The IDaaS user attribute ID used to find IDaaS users associated with an external SAML identity provider user authentication. This value is used if authenticationEnabled is true." }, "userAttributeMappings": { "type": "array", "description": "The association between the claims returned from the external SAML identity provider and IDaaS user attributes. These attributes are used to populate user attributes when it is created or modified based on an external SAML identity provider user authentication or when it is modified based on an external SAML identity provider user verification. If configured, the full set of mappings must be configured. This value is used if createUser, updateUser, or updateVerificationUser is true.", "items": { "required": [ "claim", "userAttributeId" ], "type": "object", "properties": { "claim": { "type": "string", "description": "The name of the claim (attribute) being mapped. This value must be provided when creating or modifying an attribute mapping.", "example": "email" }, "id": { "type": "string", "description": "The UUID of the SAML identity provider attribute mapping.", "example": "6781549d-433c-44ea-a42f-4705c26f3245" }, "samlIdentityProviderId": { "type": "string", "description": "The UUID of the SAML identity provider the attribute mapping belongs to.", "example": "6881549d-433c-44ea-a42f-4705c26f3245" }, "userAttribute": { "required": [ "mandatory", "name", "systemDefined", "unique" ], "type": "object", "properties": { "id": { "type": "string", "description": "The UUID for this user attribute. Generated when the user attribute is created." }, "mandatory": { "type": "boolean", "description": "A flag indicating if users must have a value for this user attribute." }, "name": { "type": "string", "description": "The name of this user attribute." }, "systemDefined": { "type": "boolean", "description": "A flag indicating if this user attribute is one of the system defined user attributes." }, "type": { "type": "string", "description": "Type of user attribute. Currently only used to specify the type of contact if the attribute is to be used for OTP delivery.", "example": "OTP_EMAIL", "enum": [ "NONE", "OTP_EMAIL", "OTP_SMS", "OTP_VOICE", "OTP_WECHAT", "OTP_WHATSAPP" ] }, "unique": { "type": "boolean", "description": "A flag indicating if this attribute is intended to be unique." } }, "description": "Information about user attribute definitions.", "title": "UserAttribute" }, "userAttributeId": { "type": "string", "description": "The UUID of the IDaaS user attribute being mapped to. This value must be provided when creating or modifying an attribute mapping.", "example": "6981549d-433c-44ea-a42f-4705c26f3245" } }, "description": "An SamlIdentityProviderAttributeMapping maps a claim (attribute) returned from an external SAML identity provider user authentication or user verification to an IDaaS user attribute.", "title": "SamlIdentityProviderAttributeMapping" } }, "userAuthMatchMappings": { "type": "array", "description": "The association between the claims returned from the external SAML identity provider and IDaaS user attributes. These attributes are used to match an existing IDaaS user based on an external SAML identity provider user authentication. If configured, the full set of mappings must be configured. This value is used if authenticationEnabled is true.", "items": { "required": [ "claim", "userAttributeId" ], "type": "object", "properties": { "claim": { "type": "string", "description": "The name of the claim (attribute) being mapped. This value must be provided when creating or modifying a user authentication match mapping.", "example": "email" }, "id": { "type": "string", "description": "The UUID of the SAML identity provider user authentication match mapping.", "example": "6781549d-433c-44ea-a42f-4705c26f3245" }, "samlIdentityProviderId": { "type": "string", "description": "The UUID of the SAML identity provider the user authentication match mapping belongs to.", "example": "6881549d-433c-44ea-a42f-4705c26f3245" }, "userAttribute": { "required": [ "mandatory", "name", "systemDefined", "unique" ], "type": "object", "properties": { "id": { "type": "string", "description": "The UUID for this user attribute. Generated when the user attribute is created." }, "mandatory": { "type": "boolean", "description": "A flag indicating if users must have a value for this user attribute." }, "name": { "type": "string", "description": "The name of this user attribute." }, "systemDefined": { "type": "boolean", "description": "A flag indicating if this user attribute is one of the system defined user attributes." }, "type": { "type": "string", "description": "Type of user attribute. Currently only used to specify the type of contact if the attribute is to be used for OTP delivery.", "example": "OTP_EMAIL", "enum": [ "NONE", "OTP_EMAIL", "OTP_SMS", "OTP_VOICE", "OTP_WECHAT", "OTP_WHATSAPP" ] }, "unique": { "type": "boolean", "description": "A flag indicating if this attribute is intended to be unique." } }, "description": "Information about user attribute definitions.", "title": "UserAttribute" }, "userAttributeId": { "type": "string", "description": "The UUID of the IDaaS user attribute being mapped to. This value must be provided when creating or modifying a user authentication match mapping.", "example": "6981549d-433c-44ea-a42f-4705c26f3245" } }, "description": "An SamlIdentityProviderUserAuthMatchMapping maps a claim (attribute) returned from an external SAML identity provide user authentication to an IDaaS User user attribute for matching purposes.", "title": "SamlIdentityProviderUserAuthMatchMapping" } }, "userClaim": { "type": "string", "description": "The external SAML identity provider claim (attribute) used to find IDaaS users associated with an external SAML identity provider user authentication. This value is used if authenticationEnabled is true." }, "userNameFormat": { "type": "string", "description": "If user name parameter is set to NameID, the value of the format of this value.", "example": "urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress" }, "userNameParameter": { "type": "string", "description": "The name of the parameter to include with the SAML authentication request that will contain the value of the user's userid. Set the value to NameID to pass this value as part of the SAML Request message.", "example": "username" }, "userVerMatchMappings": { "type": "array", "description": "The association between the claims returned from the external SAML identity provider and IDaaS user attributes. These attributes are used to match an existing IDaaS user based on an external SAML identity provider user verification. If configured, the full set of mappings must be configured. This value is used if verificationEnabled is true.", "items": { "required": [ "claim", "userAttributeId" ], "type": "object", "properties": { "claim": { "type": "string", "description": "The name of the claim (attribute) being mapped. This value must be provided when creating or modifying a user verification match mapping.", "example": "email" }, "id": { "type": "string", "description": "The UUID of the SAML identity provider user verification match mapping.", "example": "6781549d-433c-44ea-a42f-4705c26f3245" }, "samlIdentityProviderId": { "type": "string", "description": "The UUID of the SAML identity provider the user verification match mapping belongs to.", "example": "6881549d-433c-44ea-a42f-4705c26f3245" }, "userAttribute": { "required": [ "mandatory", "name", "systemDefined", "unique" ], "type": "object", "properties": { "id": { "type": "string", "description": "The UUID for this user attribute. Generated when the user attribute is created." }, "mandatory": { "type": "boolean", "description": "A flag indicating if users must have a value for this user attribute." }, "name": { "type": "string", "description": "The name of this user attribute." }, "systemDefined": { "type": "boolean", "description": "A flag indicating if this user attribute is one of the system defined user attributes." }, "type": { "type": "string", "description": "Type of user attribute. Currently only used to specify the type of contact if the attribute is to be used for OTP delivery.", "example": "OTP_EMAIL", "enum": [ "NONE", "OTP_EMAIL", "OTP_SMS", "OTP_VOICE", "OTP_WECHAT", "OTP_WHATSAPP" ] }, "unique": { "type": "boolean", "description": "A flag indicating if this attribute is intended to be unique." } }, "description": "Information about user attribute definitions.", "title": "UserAttribute" }, "userAttributeId": { "type": "string", "description": "The UUID of the IDaaS user attribute being mapped to. This value must be provided when creating or modifying a user verification match mapping.", "example": "6981549d-433c-44ea-a42f-4705c26f3245" } }, "description": "An SamlIdentityProviderUserVerMatchMapping maps a claim (attribute) returned from an external SAML identity provide user verification to an IDaaS User user attribute for matching purposes.", "title": "SamlIdentityProviderUserVerMatchMapping" } }, "verificationCertificate": { "type": "string", "description": "The verification certificate used with the external SAML identity provider.", "format": "byte" }, "verificationCertificate2": { "type": "string", "description": "The verification certificate2 used with the external SAML identity provider.", "format": "byte" }, "verificationCertificate2DN": { "type": "string", "description": "The verification certificate2 DN used with the external SAML identity provider." }, "verificationCertificate2ExpiryDate": { "type": "string", "description": "The verification certificate2 expiry date used with the external SAML identity provider.", "format": "date-time", "example": "2019-02-19T13:15:27Z" }, "verificationCertificateDN": { "type": "string", "description": "The verification certificate DN used with the external SAML identity provider." }, "verificationCertificateExpiryDate": { "type": "string", "description": "The verification certificate expiry date used with the external SAML identity provider.", "format": "date-time", "example": "2019-02-19T13:15:27Z" }, "verificationEnabled": { "type": "boolean", "description": "A flag indicating if the external SAML identity provider can be used for user verification.", "example": true } }, "description": "An SamlIdentityProvider defines the information returned about an external SAML identity provider for use with user authentication or user verification.", "title": "SamlIdentityProvider" } ``` ### 400 Bad Request #### application/json Schema ```json { "type": "object", "properties": { "errorCode": { "type": "string", "description": "Error Codes specific to cause of failure.", "example": "invalid_user_response" }, "errorMessage": { "type": "string", "description": "Additional Error Message describing the error.", "example": "Application id cannot be null" }, "parameters": { "type": "array", "description": "Optional additional error information.", "items": { "type": "object", "description": "Optional additional error information." } } }, "description": "Object containing information about errors reported by services.", "title": "ErrorInfo" } ``` ### 401 Access denied #### application/json Schema ```json { "type": "object", "properties": { "errorCode": { "type": "string", "description": "Error Codes specific to cause of failure.", "example": "invalid_user_response" }, "errorMessage": { "type": "string", "description": "Additional Error Message describing the error.", "example": "Application id cannot be null" }, "parameters": { "type": "array", "description": "Optional additional error information.", "items": { "type": "object", "description": "Optional additional error information." } } }, "description": "Object containing information about errors reported by services.", "title": "ErrorInfo" } ``` ### 403 Forbidden #### application/json Schema ```json { "type": "object", "properties": { "errorCode": { "type": "string", "description": "Error Codes specific to cause of failure.", "example": "invalid_user_response" }, "errorMessage": { "type": "string", "description": "Additional Error Message describing the error.", "example": "Application id cannot be null" }, "parameters": { "type": "array", "description": "Optional additional error information.", "items": { "type": "object", "description": "Optional additional error information." } } }, "description": "Object containing information about errors reported by services.", "title": "ErrorInfo" } ``` ### 404 Not Found #### application/json Schema ```json { "type": "object", "properties": { "errorCode": { "type": "string", "description": "Error Codes specific to cause of failure.", "example": "invalid_user_response" }, "errorMessage": { "type": "string", "description": "Additional Error Message describing the error.", "example": "Application id cannot be null" }, "parameters": { "type": "array", "description": "Optional additional error information.", "items": { "type": "object", "description": "Optional additional error information." } } }, "description": "Object containing information about errors reported by services.", "title": "ErrorInfo" } ``` ### 409 Conflict #### application/json Schema ```json { "type": "object", "properties": { "errorCode": { "type": "string", "description": "Error Codes specific to cause of failure.", "example": "invalid_user_response" }, "errorMessage": { "type": "string", "description": "Additional Error Message describing the error.", "example": "Application id cannot be null" }, "parameters": { "type": "array", "description": "Optional additional error information.", "items": { "type": "object", "description": "Optional additional error information." } } }, "description": "Object containing information about errors reported by services.", "title": "ErrorInfo" } ``` ## Security Requirements ```json [ { "AdminAPIAuthentication": [ "IDENTITYPROVIDERS:VIEW" ] } ] ```