Overview
The Identity service is an essential YaaS service. Use it to register custom identity providers for your organization.
Create and register a custom identity provider for your organization to allow your users to use YaaS with their existing accounts. With a properly configured custom identity provider in place, the YaaS OAuth2 service communicates with a remote user base to issue tokens. This allows your users to access the resources within the context of the organization for which you registered the identity provider without the need to create a new account to use with YaaS.
You can register multiple identity providers for a single organization. The custom identity provider is bound to the organization for which you register it. Using a custom identity provider, you can get tokens only for the organization you registered the custom identity provider for, as well as for all projects in that organization.
API Reference
/registration-metadata
/registration-metadata
get
Get the YaaS OAuth2 service configuration metadata. You must register this metadata in the identity provider to establish successful communication between the identity provider and the OAuth2 service.
get /registration-metadata
Get the YaaS OAuth2 service configuration metadata. You must register this metadata in the identity provider to establish successful communication between the identity provider and the OAuth2 service.
/providers
/providers
get
Use this endpoint to fetch all identity providers registered for your organization in YaaS.
Security/Access Control: To access this method, an access token must be issued for the requested organization, and have the hybris.org_manage scope.
post
Use this endpoint to register a new identity provider for your organization in YaaS.
Security / Access Control: To access this method, an access token must be issued for the requested organization, and have the hybris.org_manage scope.
get /providers
Use this endpoint to fetch all identity providers registered for your organization in YaaS.
Security/Access Control: To access this method, an access token must be issued for the requested organization, and have the hybris.org_manage scope.
Headers
- Authorization: required (string)
Used to send a valid OAuth2 access token.
Example:
Bearer access_token
Query Parameters
- totalCount: (boolean)
This parameter requests to return the total number of object in the collection fulfilling the criteria together with the response. This number will be returned in the 'hybris-count' header.
Example:
true - pageNumber: (integer - default: 1 - minimum: 1)
The page number to be retrieved where the size of the pages must be specified by the pageSize parameter. The number of the first page is 1.
Example:
1 - pageSize: (integer - default: 16 - minimum: 1)
The number of documents being retrieved on the page.
Example:
16
HTTP status code 200
List of the identity providers registered for your organization has been successfully retrieved.
Headers
- hybris-count: (integer)
The total number of objects that fulfil the criteria.
Example:
1000 - Link: required (string - repeat: true)
Link to the current page, the next page and the previous page. Marked accordingly with rel self, rel next and rel prev. The syntax must be conform to RFC-5988. The link to the current page (self) is required and must be provided always. The link to the next page (next) is optional. If not present, the next page is not available, as the current page is the last page of the result. The link to the previous page (prev) is optional. If not present, the previous page is not available, as the current page is the first page of the result.
Example:
<http://sample.com?pageNumber=2&pageSize=10>; rel="self", <http://sample.com?pageNumber=3&pageSize=10>; rel="next"
Body
Type: application/json
Schema:
{
"$schema": "http://json-schema.org/draft-04/schema",
"type": "object",
"title": "List of the **Identity Provider**'s registered for the organization in the **YaaS** (sorted ascending by the display name).",
"properties": {
"projects": {
"description": "List of the **Identity Provider**'s.",
"type": "array",
"items": {
"$schema": "http://json-schema.org/draft-04/schema",
"type": "object",
"title": "Create Application",
"required": [
"id",
"displayName"
],
"properties": {
"id": {
"description": "Identifier of the **Identity Provider** in the **YaaS**.",
"type": "string"
},
"displayName": {
"description": "Display name of the **Identity Provider**.",
"type": "string"
}
}
}
}
}
}
Example:
[
{
"id": "15bca5db-ff30-41cc-b514-7e83d93ec8d9",
"displayName": "Production IDP (https://someorg.io)"
},
{
"id": "4dd154cd-5d60-4575-a36d-738cf05f938d",
"displayName": "Test IDP (https://test.someorg.io)"
}
]
HTTP status code 400
Request was syntactically incorrect. Any details will be provided within the response payload.
Body
Type: application/json
Schema:
{
"$schema": "http://json-schema.org/draft-04/schema#",
"title": "error",
"description": "Schema for API specified errors.",
"type": "object",
"properties": {
"status": {
"type": "integer",
"description": "original HTTP error code, should be consistent with the response HTTP code",
"minimum": 100,
"maximum": 599
},
"type": {
"type": "string",
"description": "classification of the error type, lower case with underscore eg validation_failure",
"pattern": "[a-z]+[a-z_]*[a-z]+"
},
"message": {
"type": "string",
"description": "descriptive error message for debugging"
},
"moreInfo": {
"type": "string",
"format": "uri",
"description": "link to documentation to investigate further and finding support"
},
"details": {
"type": "array",
"description": "list of problems causing this error",
"items": {
"$schema": "http://json-schema.org/draft-04/schema#",
"title": "errorDetail",
"description": "schema for specific error cause",
"type": "object",
"properties": {
"field": {
"type": "string",
"description": "a bean notation expression specifying the element in request data causing the error, eg product.variants[3].name, this can be empty if violation was not field specific"
},
"type": {
"type": "string",
"description": "classification of the error detail type, lower case with underscore eg missing_value, this value must be always interpreted in context of the general error type.",
"pattern": "[a-z]+[a-z_]*[a-z]+"
},
"message": {
"type": "string",
"description": "descriptive error detail message for debugging"
},
"moreInfo": {
"type": "string",
"format": "uri",
"description": "link to documentation to investigate further and finding support for error detail"
}
},
"required": [
"type"
]
}
}
},
"required": [
"status",
"type"
]
}
Example:
{
"status": 400,
"message": "There are validation problems, see details section for more information",
"moreInfo": "https://api.yaas.io/patterns/errortypes.html",
"type": "validation_violation",
"details": [
{
"field": "pageNumber",
"message": "must be a positive number",
"type": "invalid_query_parameter"
}
]
}
HTTP status code 401
Given request is unauthorized. Bad or expired token. Reauthenticate the user. Any details will be provided within the response payload.
Body
Type: application/json
Schema:
{
"$schema": "http://json-schema.org/draft-04/schema#",
"title": "error",
"description": "Schema for API specified errors.",
"type": "object",
"properties": {
"status": {
"type": "integer",
"description": "original HTTP error code, should be consistent with the response HTTP code",
"minimum": 100,
"maximum": 599
},
"type": {
"type": "string",
"description": "classification of the error type, lower case with underscore eg validation_failure",
"pattern": "[a-z]+[a-z_]*[a-z]+"
},
"message": {
"type": "string",
"description": "descriptive error message for debugging"
},
"moreInfo": {
"type": "string",
"format": "uri",
"description": "link to documentation to investigate further and finding support"
},
"details": {
"type": "array",
"description": "list of problems causing this error",
"items": {
"$schema": "http://json-schema.org/draft-04/schema#",
"title": "errorDetail",
"description": "schema for specific error cause",
"type": "object",
"properties": {
"field": {
"type": "string",
"description": "a bean notation expression specifying the element in request data causing the error, eg product.variants[3].name, this can be empty if violation was not field specific"
},
"type": {
"type": "string",
"description": "classification of the error detail type, lower case with underscore eg missing_value, this value must be always interpreted in context of the general error type.",
"pattern": "[a-z]+[a-z_]*[a-z]+"
},
"message": {
"type": "string",
"description": "descriptive error detail message for debugging"
},
"moreInfo": {
"type": "string",
"format": "uri",
"description": "link to documentation to investigate further and finding support for error detail"
}
},
"required": [
"type"
]
}
}
},
"required": [
"status",
"type"
]
}
Example:
{
"status": 401,
"message": "Authorization: Unauthorized. Bearer TOKEN is invalid",
"type": "insufficient_credentials",
"moreInfo": "https://api.yaas.io/patterns/errortypes.html"
}
HTTP status code 403
Evaluated request scopes in access token are not sufficient and do not match required scopes.
Body
Type: application/json
Schema:
{
"$schema": "http://json-schema.org/draft-04/schema#",
"title": "error",
"description": "Schema for API specified errors.",
"type": "object",
"properties": {
"status": {
"type": "integer",
"description": "original HTTP error code, should be consistent with the response HTTP code",
"minimum": 100,
"maximum": 599
},
"type": {
"type": "string",
"description": "classification of the error type, lower case with underscore eg validation_failure",
"pattern": "[a-z]+[a-z_]*[a-z]+"
},
"message": {
"type": "string",
"description": "descriptive error message for debugging"
},
"moreInfo": {
"type": "string",
"format": "uri",
"description": "link to documentation to investigate further and finding support"
},
"details": {
"type": "array",
"description": "list of problems causing this error",
"items": {
"$schema": "http://json-schema.org/draft-04/schema#",
"title": "errorDetail",
"description": "schema for specific error cause",
"type": "object",
"properties": {
"field": {
"type": "string",
"description": "a bean notation expression specifying the element in request data causing the error, eg product.variants[3].name, this can be empty if violation was not field specific"
},
"type": {
"type": "string",
"description": "classification of the error detail type, lower case with underscore eg missing_value, this value must be always interpreted in context of the general error type.",
"pattern": "[a-z]+[a-z_]*[a-z]+"
},
"message": {
"type": "string",
"description": "descriptive error detail message for debugging"
},
"moreInfo": {
"type": "string",
"format": "uri",
"description": "link to documentation to investigate further and finding support for error detail"
}
},
"required": [
"type"
]
}
}
},
"required": [
"status",
"type"
]
}
Example:
{
"status": 403,
"message": "Given request does not have required scopes in access token. It is not authorized to perform this operation.",
"type": "insufficient_permissions"
}
post /providers
Use this endpoint to register a new identity provider for your organization in YaaS.
Security / Access Control: To access this method, an access token must be issued for the requested organization, and have the hybris.org_manage scope.
Headers
- Authorization: required (string)
Used to send a valid OAuth2 access token.
Example:
Bearer access_token
Body
Type: application/json
Schema:
{
"$schema": "http://json-schema.org/draft-04/schema",
"type": "object",
"title": "Payload for the new **Identity Provider**.",
"required": [
"displayName",
"openidConfiguration"
],
"properties": {
"displayName": {
"description": "Display name of the **Identity Provider**.",
"type": "string"
},
"credentials": {
"description": "Credentials, which will be used in communication with the **Identity Provider**. Client registered with this credentials in the **Identity Provider**, must be configured according to the settings, which can be fetched from the */registration-metadata* endpoint.",
"type": "object",
"$schema": "http://json-schema.org/draft-04/schema",
"required": [
"clientId",
"clientSecret"
],
"properties": {
"clientId": {
"description": "Client identifier",
"type": "string"
},
"clientSecret": {
"description": "Client secret",
"type": "string"
}
}
},
"openidConfiguration": {
"description": "OpenID Provider metadata in the format defined in the specification: http://openid.net/specs/openid-connect-discovery-1_0.html#ProviderMetadata. If the **Identity Provider** supports OpenID Connect Discovery (http://openid.net/specs/openid-connect-discovery-1_0.html) you can make GET request to its */.well-known/openid-configuration* endpoint, copy the response, and paste it to this section.",
"type": "object",
"$schema": "http://json-schema.org/draft-04/schema",
"required": [
"issuer"
],
"properties": {
"issuer": {
"description": "URL using the https scheme with no query or fragment component that the **Identity Provider** asserts as its Issuer Identifier. If Issuer discovery is supported (see Section 2), this value MUST be identical to the issuer value returned by WebFinger. This also MUST be identical to the iss Claim value in ID Tokens issued from this Issuer.",
"type": "string"
},
"end_session_endpoint": {
"description": "URL of the **Identity Provider**'s OpenID Connect 1.0 end_session endpoint.",
"type": "string"
},
"authorization_endpoint": {
"description": "URL of the **Identity Provider**'s OAuth 2.0 Authorization Endpoint.",
"type": "string"
},
"token_endpoint": {
"description": "URL of the **Identity Provider**'s OAuth 2.0 Token Endpoint.",
"type": "string"
},
"jwks_uri": {
"description": "REQUIRED if *jwks* is NOT specified. URL of the **Identity Provider**'s JSON Web Key Set [JWK] document. This contains the signing key(s) the RP uses to validate signatures from the **Identity Provider**. The JWK Set MAY also contain the Server's encryption key(s), which are used by RPs to encrypt requests to the Server. When both signing and encryption keys are made available, a use (Key Use) parameter value is REQUIRED for all keys in the referenced JWK Set to indicate each key's intended usage. Although some algorithms allow the same key to be used for both signatures and encryption, doing so is NOT RECOMMENDED, as it is less secure. The JWK x5c parameter MAY be used to provide X.509 representations of keys provided. When used, the bare key values MUST still be present and MUST match those in the certificate.",
"type": "string"
},
"jwks": {
"description": "The JSON Web Key Set [JWKS] document. This contains the signing key(s) the RP uses to validate signatures from the **Identity Provider**. The JWK Set MAY also contain the Server's encryption key(s), which are used by RPs to encrypt requests to the Server. When both signing and encryption keys are made available, a use (Key Use) parameter value is REQUIRED for all keys in the referenced JWK Set to indicate each key's intended usage. Although some algorithms allow the same key to be used for both signatures and encryption, doing so is NOT RECOMMENDED, as it is less secure. The JWK x5c parameter MAY be used to provide X.509 representations of keys provided. When used, the bare key values MUST still be present and MUST match those in the certificate.",
"type": "object",
"$schema": "http://json-schema.org/draft-04/schema",
"title": "Set of the *JSON Web Key*'s",
"required": [
"keys"
],
"properties": {
"keys": {
"description": "Set of the *JSON web key*'s",
"type": "array",
"items": {
"$schema": "http://json-schema.org/draft-04/schema",
"title": "JSON Web Key",
"description": "The JSON Web Key [JWK] document.",
"type": "object",
"required": [
"kty"
],
"properties": {
"kty": {
"description": "Key Type - identifies the cryptographic algorithm family used with the key, such as *RSA* or *EC*. The parameter values should either be registered in the IANA *JSON Web Key Types* registry established by [JWA - https://tools.ietf.org/html/rfc7517#ref-JWA] or be a value that contains a Collision-Resistant Name. The parameter value is a case-sensitive string. A list of defined values can be found in the IANA *JSON Web Key Types* registry established by [JWA]; the initial contents of this registry are the values defined in Section 6.1 of [JWA].",
"type": "string"
},
"use": {
"description": "Public Key Use - identifies the intended use of the public key. The parameter is employed to indicate whether a public key is used for encrypting data or verifying the signature on data. Values defined by this specification are: *sig* - signature; *enc* - encryption.",
"type": "string"
},
"alg": {
"description": "Algorithm - identifies the algorithm intended for use with the key. The values used should either be registered in the IANA *JSON Web Signature and Encryption Algorithms* registry established by [JWA - https://tools.ietf.org/html/rfc7517#ref-JWA] or be a value that contains a Collision-Resistant Name. The value is a case-sensitive ASCII string.",
"type": "string"
},
"kid": {
"description": "Key ID - is used to match a specific key. This is used, for instance, to choose among a set of keys within a JWK Set during key rollover. The structure of the value is unspecified. When *kid* values are used within a JWK Set, different keys within the JWK Set SHOULD use distinct *kid* values (one example in which different keys might use the same *kid* value is if they have different *kty* (key type) values but are considered to be equivalent alternatives by the application using them). The *kid* value is a case-sensitive string. When used with JWS or JWE, the *kid* value is used to match a JWS or JWE *kid* Header Parameter value.",
"type": "string"
},
"x5c": {
"description": "X.509 Certificate Chain - contains a chain of one or more PKIX certificates [RFC5280]. The certificate chain is represented as a JSON array of certificate value strings. Each string in the array is a base64-encoded (Section 4 of [RFC4648] --not base64url-encoded) DER [ITU.X690.1994] PKIX certificate value. The PKIX certificate containing the key value MUST be the first certificate. This MAY be followed by additional certificates, with each subsequent certificate being the one used to certify the previous one. The key in the first certificate MUST match the public key represented by other members of the JWK",
"type": "string"
},
"n": {
"description": "RSA public key modulus, supported only with the RSA key type.",
"type": "string"
},
"e": {
"description": "RSA public key exponent, supported only with the RSA key type.",
"type": "string"
}
}
}
}
}
},
"scopes_supported": {
"description": "Scopes supported by the OpenID Provider",
"type": "array",
"items": {
"type": "string"
}
}
}
},
"scopesGrant": {
"description": "Allows to adjust scopes grant.",
"type": "object",
"$schema": "http://json-schema.org/draft-04/schema",
"title": "Scopes grant",
"required": [
"scopesSource"
],
"properties": {
"scopesSource": {
"description": "Determines the source of scopes, which will be granted for authenticated users. Possible values are: *yaas* - for scopes managed in YaaS Builder, or *claim* - for scopes managed in the Identity Provider, and returned in ID token claim. By default *yaas* source is used.",
"type": "string",
"enum": [
"yaas",
"claim"
]
},
"claimName": {
"description": "Name of the claim containing scopes, which should be granted for the authenticated user. Works only if source is *claim*. If it is not specified, then *scope* claim will be used.",
"type": "string"
}
}
}
}
}
Example:
{
"displayName": "Production IDP (https://someorg.io)",
"credentials": {
"clientId": "a9883977-97e2-44d9-a4cb-7c2df0f7a267",
"clientSecret": "2loftph991j058ud"
},
"openidConfiguration": {
"issuer": "https://accounts.google.com",
"authorization_endpoint": "https://accounts.google.com/o/oauth2/v2/auth",
"token_endpoint": "https://www.googleapis.com/oauth2/v4/token",
"jwks_uri": "https://www.googleapis.com/oauth2/v3/certs",
"scopes_supported": [
"openid",
"email",
"profile"
]
}
}
HTTP status code 201
Identity provider has been successfully registered.
Body
Type: application/json
Schema:
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"title": "Resource Location",
"description": "Schema for showing location of the new resource.",
"properties": {
"id": {
"description": "The identifier of the created resource",
"type": "string"
},
"link": {
"description": "The link to the created resource",
"type": "string",
"format": "uri"
}
},
"required": [
"id",
"link"
]
}
Example:
{
"id": "15bca5db-ff30-41cc-b514-7e83d93ec8d9",
"link": "http://api.eu.yaas.io/hybris/identity/v1/providers/15bca5db-ff30-41cc-b514-7e83d93ec8d9"
}
HTTP status code 400
Payload validation error
Body
Type: application/json
Schema:
errorMessageExample:
{
"status": 400,
"type": "validation_violation",
"message": "Field credentials cannot be empty",
"moreInfo": "https://api.yaas.io/patterns/errortypes.html"
}
HTTP status code 401
Given request is unauthorized. Bad or expired token. Reauthenticate the user. Any details will be provided within the response payload.
Body
Type: application/json
Schema:
{
"$schema": "http://json-schema.org/draft-04/schema#",
"title": "error",
"description": "Schema for API specified errors.",
"type": "object",
"properties": {
"status": {
"type": "integer",
"description": "original HTTP error code, should be consistent with the response HTTP code",
"minimum": 100,
"maximum": 599
},
"type": {
"type": "string",
"description": "classification of the error type, lower case with underscore eg validation_failure",
"pattern": "[a-z]+[a-z_]*[a-z]+"
},
"message": {
"type": "string",
"description": "descriptive error message for debugging"
},
"moreInfo": {
"type": "string",
"format": "uri",
"description": "link to documentation to investigate further and finding support"
},
"details": {
"type": "array",
"description": "list of problems causing this error",
"items": {
"$schema": "http://json-schema.org/draft-04/schema#",
"title": "errorDetail",
"description": "schema for specific error cause",
"type": "object",
"properties": {
"field": {
"type": "string",
"description": "a bean notation expression specifying the element in request data causing the error, eg product.variants[3].name, this can be empty if violation was not field specific"
},
"type": {
"type": "string",
"description": "classification of the error detail type, lower case with underscore eg missing_value, this value must be always interpreted in context of the general error type.",
"pattern": "[a-z]+[a-z_]*[a-z]+"
},
"message": {
"type": "string",
"description": "descriptive error detail message for debugging"
},
"moreInfo": {
"type": "string",
"format": "uri",
"description": "link to documentation to investigate further and finding support for error detail"
}
},
"required": [
"type"
]
}
}
},
"required": [
"status",
"type"
]
}
Example:
{
"status": 401,
"message": "Authorization: Unauthorized. Bearer TOKEN is invalid",
"type": "insufficient_credentials",
"moreInfo": "https://api.yaas.io/patterns/errortypes.html"
}
HTTP status code 403
Evaluated request scopes in access token are not sufficient and do not match required scopes.
Body
Type: application/json
Schema:
{
"$schema": "http://json-schema.org/draft-04/schema#",
"title": "error",
"description": "Schema for API specified errors.",
"type": "object",
"properties": {
"status": {
"type": "integer",
"description": "original HTTP error code, should be consistent with the response HTTP code",
"minimum": 100,
"maximum": 599
},
"type": {
"type": "string",
"description": "classification of the error type, lower case with underscore eg validation_failure",
"pattern": "[a-z]+[a-z_]*[a-z]+"
},
"message": {
"type": "string",
"description": "descriptive error message for debugging"
},
"moreInfo": {
"type": "string",
"format": "uri",
"description": "link to documentation to investigate further and finding support"
},
"details": {
"type": "array",
"description": "list of problems causing this error",
"items": {
"$schema": "http://json-schema.org/draft-04/schema#",
"title": "errorDetail",
"description": "schema for specific error cause",
"type": "object",
"properties": {
"field": {
"type": "string",
"description": "a bean notation expression specifying the element in request data causing the error, eg product.variants[3].name, this can be empty if violation was not field specific"
},
"type": {
"type": "string",
"description": "classification of the error detail type, lower case with underscore eg missing_value, this value must be always interpreted in context of the general error type.",
"pattern": "[a-z]+[a-z_]*[a-z]+"
},
"message": {
"type": "string",
"description": "descriptive error detail message for debugging"
},
"moreInfo": {
"type": "string",
"format": "uri",
"description": "link to documentation to investigate further and finding support for error detail"
}
},
"required": [
"type"
]
}
}
},
"required": [
"status",
"type"
]
}
Example:
{
"status": 403,
"message": "Given request does not have required scopes in access token. It is not authorized to perform this operation.",
"type": "insufficient_permissions"
}
/providers/{id}
get
Use this endpoint to fetch information about the identity provider with the specified ID.
Security/Access Control: To access this method, an access token must be issued for the organization which owns the identity provider, and have the hybris.org_manage scope.
put
Use this endpoint to update the identity provider's information.
Security / Access Control: To access this method, an access token must be issued for the organization which owns the identity provider, and have the hybris.org_manage scope.
delete
Use this endpoint to delete a registered identity provider.
Security / Access Control: To access this method, an access token must be issued for the organization which owns the identity provider, and have the hybris.org_manage scope.
get /providers/{id}
Use this endpoint to fetch information about the identity provider with the specified ID.
Security/Access Control: To access this method, an access token must be issued for the organization which owns the identity provider, and have the hybris.org_manage scope.
URI Parameters
- id: required (string)
Headers
- Authorization: required (string)
Used to send a valid OAuth2 access token.
Example:
Bearer access_token
- If-None-Match: (string)
The service returns a code 200 "successfull" response and payload in the body only when the ETag header value is different to the values passed in this header. If you don't meet these criteria, the client returns a code 304 "not modified" response and does not include the payload in the body. Use this header to implement objects cache.
HTTP status code 200
Information about the specified identity provider has been retrieved successfully.
Headers
- ETag: (string)
An entity tag, is an opaque token associated with a particular state of a resource. Whenever the resource state changes, the entity tag is changed accordingly. The ETag value can be used by clients and servers to determine if a request to a resource is up-to-date by comparing the value of the ETag header on the incoming request, to the value of the ETag header present on the server. If the values match, the client request is using an up-to-date representation of the resource. If the values do not match, the client should refresh its copy of the resource to make sure it is up-to-date.
Body
Type: application/json
Schema:
{
"$schema": "http://json-schema.org/draft-04/schema",
"type": "object",
"title": "Create Application",
"required": [
"id",
"displayName",
"openidConfiguration",
"metadata"
],
"properties": {
"id": {
"description": "Identifier of the **Identity Provider** in the **YaaS**.",
"type": "string"
},
"displayName": {
"description": "Display name of the **Identity Provider**.",
"type": "string"
},
"credentials": {
"description": "Credentials, which will be used in communication with the **Identity Provider**. Client registered with this credentials in the **Identity Provider**, must be configured according to the settings, which can be fetched from the */registration-metadata* endpoint.",
"type": "object",
"$schema": "http://json-schema.org/draft-04/schema",
"required": [
"clientId",
"clientSecret"
],
"properties": {
"clientId": {
"description": "Client identifier",
"type": "string"
},
"clientSecret": {
"description": "Client secret",
"type": "string"
}
}
},
"openidConfiguration": {
"description": "OpenID Provider metadata in the format defined in the specification: http://openid.net/specs/openid-connect-discovery-1_0.html#ProviderMetadata. If the **Identity Provider** supports OpenID Connect Discovery (http://openid.net/specs/openid-connect-discovery-1_0.html) you can make GET request to its */.well-known/openid-configuration* endpoint, copy the response, and paste it to this section.",
"type": "object",
"$schema": "http://json-schema.org/draft-04/schema",
"required": [
"issuer"
],
"properties": {
"issuer": {
"description": "URL using the https scheme with no query or fragment component that the **Identity Provider** asserts as its Issuer Identifier. If Issuer discovery is supported (see Section 2), this value MUST be identical to the issuer value returned by WebFinger. This also MUST be identical to the iss Claim value in ID Tokens issued from this Issuer.",
"type": "string"
},
"end_session_endpoint": {
"description": "URL of the **Identity Provider**'s OpenID Connect 1.0 end_session endpoint.",
"type": "string"
},
"authorization_endpoint": {
"description": "URL of the **Identity Provider**'s OAuth 2.0 Authorization Endpoint.",
"type": "string"
},
"token_endpoint": {
"description": "URL of the **Identity Provider**'s OAuth 2.0 Token Endpoint.",
"type": "string"
},
"jwks_uri": {
"description": "REQUIRED if *jwks* is NOT specified. URL of the **Identity Provider**'s JSON Web Key Set [JWK] document. This contains the signing key(s) the RP uses to validate signatures from the **Identity Provider**. The JWK Set MAY also contain the Server's encryption key(s), which are used by RPs to encrypt requests to the Server. When both signing and encryption keys are made available, a use (Key Use) parameter value is REQUIRED for all keys in the referenced JWK Set to indicate each key's intended usage. Although some algorithms allow the same key to be used for both signatures and encryption, doing so is NOT RECOMMENDED, as it is less secure. The JWK x5c parameter MAY be used to provide X.509 representations of keys provided. When used, the bare key values MUST still be present and MUST match those in the certificate.",
"type": "string"
},
"jwks": {
"description": "The JSON Web Key Set [JWKS] document. This contains the signing key(s) the RP uses to validate signatures from the **Identity Provider**. The JWK Set MAY also contain the Server's encryption key(s), which are used by RPs to encrypt requests to the Server. When both signing and encryption keys are made available, a use (Key Use) parameter value is REQUIRED for all keys in the referenced JWK Set to indicate each key's intended usage. Although some algorithms allow the same key to be used for both signatures and encryption, doing so is NOT RECOMMENDED, as it is less secure. The JWK x5c parameter MAY be used to provide X.509 representations of keys provided. When used, the bare key values MUST still be present and MUST match those in the certificate.",
"type": "object",
"$schema": "http://json-schema.org/draft-04/schema",
"title": "Set of the *JSON Web Key*'s",
"required": [
"keys"
],
"properties": {
"keys": {
"description": "Set of the *JSON web key*'s",
"type": "array",
"items": {
"$schema": "http://json-schema.org/draft-04/schema",
"title": "JSON Web Key",
"description": "The JSON Web Key [JWK] document.",
"type": "object",
"required": [
"kty"
],
"properties": {
"kty": {
"description": "Key Type - identifies the cryptographic algorithm family used with the key, such as *RSA* or *EC*. The parameter values should either be registered in the IANA *JSON Web Key Types* registry established by [JWA - https://tools.ietf.org/html/rfc7517#ref-JWA] or be a value that contains a Collision-Resistant Name. The parameter value is a case-sensitive string. A list of defined values can be found in the IANA *JSON Web Key Types* registry established by [JWA]; the initial contents of this registry are the values defined in Section 6.1 of [JWA].",
"type": "string"
},
"use": {
"description": "Public Key Use - identifies the intended use of the public key. The parameter is employed to indicate whether a public key is used for encrypting data or verifying the signature on data. Values defined by this specification are: *sig* - signature; *enc* - encryption.",
"type": "string"
},
"alg": {
"description": "Algorithm - identifies the algorithm intended for use with the key. The values used should either be registered in the IANA *JSON Web Signature and Encryption Algorithms* registry established by [JWA - https://tools.ietf.org/html/rfc7517#ref-JWA] or be a value that contains a Collision-Resistant Name. The value is a case-sensitive ASCII string.",
"type": "string"
},
"kid": {
"description": "Key ID - is used to match a specific key. This is used, for instance, to choose among a set of keys within a JWK Set during key rollover. The structure of the value is unspecified. When *kid* values are used within a JWK Set, different keys within the JWK Set SHOULD use distinct *kid* values (one example in which different keys might use the same *kid* value is if they have different *kty* (key type) values but are considered to be equivalent alternatives by the application using them). The *kid* value is a case-sensitive string. When used with JWS or JWE, the *kid* value is used to match a JWS or JWE *kid* Header Parameter value.",
"type": "string"
},
"x5c": {
"description": "X.509 Certificate Chain - contains a chain of one or more PKIX certificates [RFC5280]. The certificate chain is represented as a JSON array of certificate value strings. Each string in the array is a base64-encoded (Section 4 of [RFC4648] --not base64url-encoded) DER [ITU.X690.1994] PKIX certificate value. The PKIX certificate containing the key value MUST be the first certificate. This MAY be followed by additional certificates, with each subsequent certificate being the one used to certify the previous one. The key in the first certificate MUST match the public key represented by other members of the JWK",
"type": "string"
},
"n": {
"description": "RSA public key modulus, supported only with the RSA key type.",
"type": "string"
},
"e": {
"description": "RSA public key exponent, supported only with the RSA key type.",
"type": "string"
}
}
}
}
}
},
"scopes_supported": {
"description": "Scopes supported by the OpenID Provider",
"type": "array",
"items": {
"type": "string"
}
}
}
},
"scopesGrant": {
"description": "Allows to adjust scopes grant.",
"type": "object",
"$schema": "http://json-schema.org/draft-04/schema",
"title": "Scopes grant",
"required": [
"scopesSource"
],
"properties": {
"scopesSource": {
"description": "Determines the source of scopes, which will be granted for authenticated users. Possible values are: *yaas* - for scopes managed in YaaS Builder, or *claim* - for scopes managed in the Identity Provider, and returned in ID token claim. By default *yaas* source is used.",
"type": "string",
"enum": [
"yaas",
"claim"
]
},
"claimName": {
"description": "Name of the claim containing scopes, which should be granted for the authenticated user. Works only if source is *claim*. If it is not specified, then *scope* claim will be used.",
"type": "string"
}
}
},
"metadata": {
"description": "Object metadata",
"type": "object",
"$schema": "http://json-schema.org/draft-04/schema",
"required": [
"version",
"createdAt",
"modifiedAt"
],
"properties": {
"version": {
"description": "Object version",
"type": "string"
},
"createdAt": {
"description": "Object creation date and time",
"type": "string",
"format": "date-time"
},
"modifiedAt": {
"description": "Object last modification date and time",
"type": "string",
"format": "date-time"
}
}
}
}
}
Example:
{
"id": "15bca5db-ff30-41cc-b514-7e83d93ec8d9",
"displayName": "Production IDP (https://someorg.io)",
"credentials": {
"clientId": "a9883977-97e2-44d9-a4cb-7c2df0f7a267",
"clientSecret": "2loftph991j058ud"
},
"openidConfiguration": {
"issuer": "https://accounts.google.com",
"authorization_endpoint": "https://accounts.google.com/o/oauth2/v2/auth",
"token_endpoint": "https://www.googleapis.com/oauth2/v4/token",
"jwks_uri": "https://www.googleapis.com/oauth2/v3/certs",
"scopes_supported": [
"openid",
"email",
"profile"
]
},
"metadata": {
"version": "645b0cca-8d90-4382-ba0e-c52e1f327e73",
"createdAt": "2017-06-14T09:53:42.523+0000",
"modifiedAt": "2017-06-14T12:45:21.146+0000"
}
}
HTTP status code 304
The object's data hasn't been modified. The service returns the status only if you passed the If-None-Match header in the request. Response does not contain any payload.
Headers
- ETag: (string)
An entity tag, is an opaque token associated with a particular state of a resource. Whenever the resource state changes, the entity tag is changed accordingly. The ETag value can be used by clients and servers to determine if a request to a resource is up-to-date by comparing the value of the ETag header on the incoming request, to the value of the ETag header present on the server. If the values match, the client request is using an up-to-date representation of the resource. If the values do not match, the client should refresh its copy of the resource to make sure it is up-to-date.
HTTP status code 401
Given request is unauthorized. Bad or expired token. Reauthenticate the user. Any details will be provided within the response payload.
Body
Type: application/json
Schema:
{
"$schema": "http://json-schema.org/draft-04/schema#",
"title": "error",
"description": "Schema for API specified errors.",
"type": "object",
"properties": {
"status": {
"type": "integer",
"description": "original HTTP error code, should be consistent with the response HTTP code",
"minimum": 100,
"maximum": 599
},
"type": {
"type": "string",
"description": "classification of the error type, lower case with underscore eg validation_failure",
"pattern": "[a-z]+[a-z_]*[a-z]+"
},
"message": {
"type": "string",
"description": "descriptive error message for debugging"
},
"moreInfo": {
"type": "string",
"format": "uri",
"description": "link to documentation to investigate further and finding support"
},
"details": {
"type": "array",
"description": "list of problems causing this error",
"items": {
"$schema": "http://json-schema.org/draft-04/schema#",
"title": "errorDetail",
"description": "schema for specific error cause",
"type": "object",
"properties": {
"field": {
"type": "string",
"description": "a bean notation expression specifying the element in request data causing the error, eg product.variants[3].name, this can be empty if violation was not field specific"
},
"type": {
"type": "string",
"description": "classification of the error detail type, lower case with underscore eg missing_value, this value must be always interpreted in context of the general error type.",
"pattern": "[a-z]+[a-z_]*[a-z]+"
},
"message": {
"type": "string",
"description": "descriptive error detail message for debugging"
},
"moreInfo": {
"type": "string",
"format": "uri",
"description": "link to documentation to investigate further and finding support for error detail"
}
},
"required": [
"type"
]
}
}
},
"required": [
"status",
"type"
]
}
Example:
{
"status": 401,
"message": "Authorization: Unauthorized. Bearer TOKEN is invalid",
"type": "insufficient_credentials",
"moreInfo": "https://api.yaas.io/patterns/errortypes.html"
}
HTTP status code 403
Evaluated request scopes in access token are not sufficient and do not match required scopes.
Body
Type: application/json
Schema:
{
"$schema": "http://json-schema.org/draft-04/schema#",
"title": "error",
"description": "Schema for API specified errors.",
"type": "object",
"properties": {
"status": {
"type": "integer",
"description": "original HTTP error code, should be consistent with the response HTTP code",
"minimum": 100,
"maximum": 599
},
"type": {
"type": "string",
"description": "classification of the error type, lower case with underscore eg validation_failure",
"pattern": "[a-z]+[a-z_]*[a-z]+"
},
"message": {
"type": "string",
"description": "descriptive error message for debugging"
},
"moreInfo": {
"type": "string",
"format": "uri",
"description": "link to documentation to investigate further and finding support"
},
"details": {
"type": "array",
"description": "list of problems causing this error",
"items": {
"$schema": "http://json-schema.org/draft-04/schema#",
"title": "errorDetail",
"description": "schema for specific error cause",
"type": "object",
"properties": {
"field": {
"type": "string",
"description": "a bean notation expression specifying the element in request data causing the error, eg product.variants[3].name, this can be empty if violation was not field specific"
},
"type": {
"type": "string",
"description": "classification of the error detail type, lower case with underscore eg missing_value, this value must be always interpreted in context of the general error type.",
"pattern": "[a-z]+[a-z_]*[a-z]+"
},
"message": {
"type": "string",
"description": "descriptive error detail message for debugging"
},
"moreInfo": {
"type": "string",
"format": "uri",
"description": "link to documentation to investigate further and finding support for error detail"
}
},
"required": [
"type"
]
}
}
},
"required": [
"status",
"type"
]
}
Example:
{
"status": 403,
"message": "Given request does not have required scopes in access token. It is not authorized to perform this operation.",
"type": "insufficient_permissions"
}
HTTP status code 404
There is no client with the given identifier.
Body
Type: application/json
Schema:
errorMessageExample:
{
"status": 404,
"type": "element_non_existing",
"message": "Identity Provider with requested ID does not exist or belongs to the other organization.",
"moreInfo": "https://api.yaas.io/patterns/errortypes.html"
}
put /providers/{id}
Use this endpoint to update the identity provider's information.
Security / Access Control: To access this method, an access token must be issued for the organization which owns the identity provider, and have the hybris.org_manage scope.
URI Parameters
- id: required (string)
Headers
- Authorization: required (string)
Used to send a valid OAuth2 access token.
Example:
Bearer access_token
- If-Match: (string)
The request succeeds only when the value of this header matches the object version, stored in the ETag header. If the criteria is not met, the service returns a code 412 response and doesn't update the object. Use it to implement Optimistic Locking.
Body
Type: application/json
Schema:
{
"$schema": "http://json-schema.org/draft-04/schema",
"type": "object",
"title": "Payload for the new **Identity Provider**.",
"required": [
"displayName",
"openidConfiguration"
],
"properties": {
"displayName": {
"description": "Display name of the **Identity Provider**.",
"type": "string"
},
"credentials": {
"description": "Credentials, which will be used in communication with the **Identity Provider**. Client registered with this credentials in the **Identity Provider**, must be configured according to the settings, which can be fetched from the */registration-metadata* endpoint.",
"type": "object",
"$schema": "http://json-schema.org/draft-04/schema",
"required": [
"clientId",
"clientSecret"
],
"properties": {
"clientId": {
"description": "Client identifier",
"type": "string"
},
"clientSecret": {
"description": "Client secret",
"type": "string"
}
}
},
"openidConfiguration": {
"description": "OpenID Provider metadata in the format defined in the specification: http://openid.net/specs/openid-connect-discovery-1_0.html#ProviderMetadata. If the **Identity Provider** supports OpenID Connect Discovery (http://openid.net/specs/openid-connect-discovery-1_0.html) you can make GET request to its */.well-known/openid-configuration* endpoint, copy the response, and paste it to this section.",
"type": "object",
"$schema": "http://json-schema.org/draft-04/schema",
"required": [
"issuer"
],
"properties": {
"issuer": {
"description": "URL using the https scheme with no query or fragment component that the **Identity Provider** asserts as its Issuer Identifier. If Issuer discovery is supported (see Section 2), this value MUST be identical to the issuer value returned by WebFinger. This also MUST be identical to the iss Claim value in ID Tokens issued from this Issuer.",
"type": "string"
},
"end_session_endpoint": {
"description": "URL of the **Identity Provider**'s OpenID Connect 1.0 end_session endpoint.",
"type": "string"
},
"authorization_endpoint": {
"description": "URL of the **Identity Provider**'s OAuth 2.0 Authorization Endpoint.",
"type": "string"
},
"token_endpoint": {
"description": "URL of the **Identity Provider**'s OAuth 2.0 Token Endpoint.",
"type": "string"
},
"jwks_uri": {
"description": "REQUIRED if *jwks* is NOT specified. URL of the **Identity Provider**'s JSON Web Key Set [JWK] document. This contains the signing key(s) the RP uses to validate signatures from the **Identity Provider**. The JWK Set MAY also contain the Server's encryption key(s), which are used by RPs to encrypt requests to the Server. When both signing and encryption keys are made available, a use (Key Use) parameter value is REQUIRED for all keys in the referenced JWK Set to indicate each key's intended usage. Although some algorithms allow the same key to be used for both signatures and encryption, doing so is NOT RECOMMENDED, as it is less secure. The JWK x5c parameter MAY be used to provide X.509 representations of keys provided. When used, the bare key values MUST still be present and MUST match those in the certificate.",
"type": "string"
},
"jwks": {
"description": "The JSON Web Key Set [JWKS] document. This contains the signing key(s) the RP uses to validate signatures from the **Identity Provider**. The JWK Set MAY also contain the Server's encryption key(s), which are used by RPs to encrypt requests to the Server. When both signing and encryption keys are made available, a use (Key Use) parameter value is REQUIRED for all keys in the referenced JWK Set to indicate each key's intended usage. Although some algorithms allow the same key to be used for both signatures and encryption, doing so is NOT RECOMMENDED, as it is less secure. The JWK x5c parameter MAY be used to provide X.509 representations of keys provided. When used, the bare key values MUST still be present and MUST match those in the certificate.",
"type": "object",
"$schema": "http://json-schema.org/draft-04/schema",
"title": "Set of the *JSON Web Key*'s",
"required": [
"keys"
],
"properties": {
"keys": {
"description": "Set of the *JSON web key*'s",
"type": "array",
"items": {
"$schema": "http://json-schema.org/draft-04/schema",
"title": "JSON Web Key",
"description": "The JSON Web Key [JWK] document.",
"type": "object",
"required": [
"kty"
],
"properties": {
"kty": {
"description": "Key Type - identifies the cryptographic algorithm family used with the key, such as *RSA* or *EC*. The parameter values should either be registered in the IANA *JSON Web Key Types* registry established by [JWA - https://tools.ietf.org/html/rfc7517#ref-JWA] or be a value that contains a Collision-Resistant Name. The parameter value is a case-sensitive string. A list of defined values can be found in the IANA *JSON Web Key Types* registry established by [JWA]; the initial contents of this registry are the values defined in Section 6.1 of [JWA].",
"type": "string"
},
"use": {
"description": "Public Key Use - identifies the intended use of the public key. The parameter is employed to indicate whether a public key is used for encrypting data or verifying the signature on data. Values defined by this specification are: *sig* - signature; *enc* - encryption.",
"type": "string"
},
"alg": {
"description": "Algorithm - identifies the algorithm intended for use with the key. The values used should either be registered in the IANA *JSON Web Signature and Encryption Algorithms* registry established by [JWA - https://tools.ietf.org/html/rfc7517#ref-JWA] or be a value that contains a Collision-Resistant Name. The value is a case-sensitive ASCII string.",
"type": "string"
},
"kid": {
"description": "Key ID - is used to match a specific key. This is used, for instance, to choose among a set of keys within a JWK Set during key rollover. The structure of the value is unspecified. When *kid* values are used within a JWK Set, different keys within the JWK Set SHOULD use distinct *kid* values (one example in which different keys might use the same *kid* value is if they have different *kty* (key type) values but are considered to be equivalent alternatives by the application using them). The *kid* value is a case-sensitive string. When used with JWS or JWE, the *kid* value is used to match a JWS or JWE *kid* Header Parameter value.",
"type": "string"
},
"x5c": {
"description": "X.509 Certificate Chain - contains a chain of one or more PKIX certificates [RFC5280]. The certificate chain is represented as a JSON array of certificate value strings. Each string in the array is a base64-encoded (Section 4 of [RFC4648] --not base64url-encoded) DER [ITU.X690.1994] PKIX certificate value. The PKIX certificate containing the key value MUST be the first certificate. This MAY be followed by additional certificates, with each subsequent certificate being the one used to certify the previous one. The key in the first certificate MUST match the public key represented by other members of the JWK",
"type": "string"
},
"n": {
"description": "RSA public key modulus, supported only with the RSA key type.",
"type": "string"
},
"e": {
"description": "RSA public key exponent, supported only with the RSA key type.",
"type": "string"
}
}
}
}
}
},
"scopes_supported": {
"description": "Scopes supported by the OpenID Provider",
"type": "array",
"items": {
"type": "string"
}
}
}
},
"scopesGrant": {
"description": "Allows to adjust scopes grant.",
"type": "object",
"$schema": "http://json-schema.org/draft-04/schema",
"title": "Scopes grant",
"required": [
"scopesSource"
],
"properties": {
"scopesSource": {
"description": "Determines the source of scopes, which will be granted for authenticated users. Possible values are: *yaas* - for scopes managed in YaaS Builder, or *claim* - for scopes managed in the Identity Provider, and returned in ID token claim. By default *yaas* source is used.",
"type": "string",
"enum": [
"yaas",
"claim"
]
},
"claimName": {
"description": "Name of the claim containing scopes, which should be granted for the authenticated user. Works only if source is *claim*. If it is not specified, then *scope* claim will be used.",
"type": "string"
}
}
}
}
}
Example:
{
"displayName": "Production IDP (https://someorg.io)",
"credentials": {
"clientId": "a9883977-97e2-44d9-a4cb-7c2df0f7a267",
"clientSecret": "2loftph991j058ud"
},
"openidConfiguration": {
"issuer": "https://accounts.google.com",
"authorization_endpoint": "https://accounts.google.com/o/oauth2/v2/auth",
"token_endpoint": "https://www.googleapis.com/oauth2/v4/token",
"jwks_uri": "https://www.googleapis.com/oauth2/v3/certs",
"scopes_supported": [
"openid",
"email",
"profile"
]
}
}
HTTP status code 204
Identity provider's information has been successfully updated.
HTTP status code 400
Payload validation error.
Body
Type: application/json
Schema:
errorMessageExample:
{
"status": 400,
"type": "validation_violation",
"message": "Field credentials cannot be empty",
"moreInfo": "https://api.yaas.io/patterns/errortypes.html"
}
HTTP status code 401
Given request is unauthorized. Bad or expired token. Reauthenticate the user. Any details will be provided within the response payload.
Body
Type: application/json
Schema:
{
"$schema": "http://json-schema.org/draft-04/schema#",
"title": "error",
"description": "Schema for API specified errors.",
"type": "object",
"properties": {
"status": {
"type": "integer",
"description": "original HTTP error code, should be consistent with the response HTTP code",
"minimum": 100,
"maximum": 599
},
"type": {
"type": "string",
"description": "classification of the error type, lower case with underscore eg validation_failure",
"pattern": "[a-z]+[a-z_]*[a-z]+"
},
"message": {
"type": "string",
"description": "descriptive error message for debugging"
},
"moreInfo": {
"type": "string",
"format": "uri",
"description": "link to documentation to investigate further and finding support"
},
"details": {
"type": "array",
"description": "list of problems causing this error",
"items": {
"$schema": "http://json-schema.org/draft-04/schema#",
"title": "errorDetail",
"description": "schema for specific error cause",
"type": "object",
"properties": {
"field": {
"type": "string",
"description": "a bean notation expression specifying the element in request data causing the error, eg product.variants[3].name, this can be empty if violation was not field specific"
},
"type": {
"type": "string",
"description": "classification of the error detail type, lower case with underscore eg missing_value, this value must be always interpreted in context of the general error type.",
"pattern": "[a-z]+[a-z_]*[a-z]+"
},
"message": {
"type": "string",
"description": "descriptive error detail message for debugging"
},
"moreInfo": {
"type": "string",
"format": "uri",
"description": "link to documentation to investigate further and finding support for error detail"
}
},
"required": [
"type"
]
}
}
},
"required": [
"status",
"type"
]
}
Example:
{
"status": 401,
"message": "Authorization: Unauthorized. Bearer TOKEN is invalid",
"type": "insufficient_credentials",
"moreInfo": "https://api.yaas.io/patterns/errortypes.html"
}
HTTP status code 403
Evaluated request scopes in access token are not sufficient and do not match required scopes.
Body
Type: application/json
Schema:
{
"$schema": "http://json-schema.org/draft-04/schema#",
"title": "error",
"description": "Schema for API specified errors.",
"type": "object",
"properties": {
"status": {
"type": "integer",
"description": "original HTTP error code, should be consistent with the response HTTP code",
"minimum": 100,
"maximum": 599
},
"type": {
"type": "string",
"description": "classification of the error type, lower case with underscore eg validation_failure",
"pattern": "[a-z]+[a-z_]*[a-z]+"
},
"message": {
"type": "string",
"description": "descriptive error message for debugging"
},
"moreInfo": {
"type": "string",
"format": "uri",
"description": "link to documentation to investigate further and finding support"
},
"details": {
"type": "array",
"description": "list of problems causing this error",
"items": {
"$schema": "http://json-schema.org/draft-04/schema#",
"title": "errorDetail",
"description": "schema for specific error cause",
"type": "object",
"properties": {
"field": {
"type": "string",
"description": "a bean notation expression specifying the element in request data causing the error, eg product.variants[3].name, this can be empty if violation was not field specific"
},
"type": {
"type": "string",
"description": "classification of the error detail type, lower case with underscore eg missing_value, this value must be always interpreted in context of the general error type.",
"pattern": "[a-z]+[a-z_]*[a-z]+"
},
"message": {
"type": "string",
"description": "descriptive error detail message for debugging"
},
"moreInfo": {
"type": "string",
"format": "uri",
"description": "link to documentation to investigate further and finding support for error detail"
}
},
"required": [
"type"
]
}
}
},
"required": [
"status",
"type"
]
}
Example:
{
"status": 403,
"message": "Given request does not have required scopes in access token. It is not authorized to perform this operation.",
"type": "insufficient_permissions"
}
HTTP status code 404
Identity provider with given ID was not found.
Body
Type: application/json
Schema:
errorMessageExample:
{
"status": 404,
"type": "element_non_existing",
"message": "Identity Provider with requested ID does not exist or belongs to the other organization.",
"moreInfo": "https://api.yaas.io/patterns/errortypes.html"
}
HTTP status code 412
Update failed. Object version determined by the ETag header value does not match any of the values listed in the If-Match header. Update the local copy of the resource to the latest version and resend the request.
delete /providers/{id}
Use this endpoint to delete a registered identity provider.
Security / Access Control: To access this method, an access token must be issued for the organization which owns the identity provider, and have the hybris.org_manage scope.
URI Parameters
- id: required (string)
Headers
- Authorization: required (string)
Used to send a valid OAuth2 access token.
Example:
Bearer access_token
- If-Match: (string)
The request succeeds only when the value of this header matches the object version, stored in the ETag header. If the criteria is not met, the service returns a code 412 response and doesn't update the object. Use it to implement Optimistic Locking.
HTTP status code 204
The identity provider has been successfully deleted.
HTTP status code 401
Given request is unauthorized. Bad or expired token. Reauthenticate the user. Any details will be provided within the response payload.
Body
Type: application/json
Schema:
{
"$schema": "http://json-schema.org/draft-04/schema#",
"title": "error",
"description": "Schema for API specified errors.",
"type": "object",
"properties": {
"status": {
"type": "integer",
"description": "original HTTP error code, should be consistent with the response HTTP code",
"minimum": 100,
"maximum": 599
},
"type": {
"type": "string",
"description": "classification of the error type, lower case with underscore eg validation_failure",
"pattern": "[a-z]+[a-z_]*[a-z]+"
},
"message": {
"type": "string",
"description": "descriptive error message for debugging"
},
"moreInfo": {
"type": "string",
"format": "uri",
"description": "link to documentation to investigate further and finding support"
},
"details": {
"type": "array",
"description": "list of problems causing this error",
"items": {
"$schema": "http://json-schema.org/draft-04/schema#",
"title": "errorDetail",
"description": "schema for specific error cause",
"type": "object",
"properties": {
"field": {
"type": "string",
"description": "a bean notation expression specifying the element in request data causing the error, eg product.variants[3].name, this can be empty if violation was not field specific"
},
"type": {
"type": "string",
"description": "classification of the error detail type, lower case with underscore eg missing_value, this value must be always interpreted in context of the general error type.",
"pattern": "[a-z]+[a-z_]*[a-z]+"
},
"message": {
"type": "string",
"description": "descriptive error detail message for debugging"
},
"moreInfo": {
"type": "string",
"format": "uri",
"description": "link to documentation to investigate further and finding support for error detail"
}
},
"required": [
"type"
]
}
}
},
"required": [
"status",
"type"
]
}
Example:
{
"status": 401,
"message": "Authorization: Unauthorized. Bearer TOKEN is invalid",
"type": "insufficient_credentials",
"moreInfo": "https://api.yaas.io/patterns/errortypes.html"
}
HTTP status code 403
Evaluated request scopes in access token are not sufficient and do not match required scopes.
Body
Type: application/json
Schema:
{
"$schema": "http://json-schema.org/draft-04/schema#",
"title": "error",
"description": "Schema for API specified errors.",
"type": "object",
"properties": {
"status": {
"type": "integer",
"description": "original HTTP error code, should be consistent with the response HTTP code",
"minimum": 100,
"maximum": 599
},
"type": {
"type": "string",
"description": "classification of the error type, lower case with underscore eg validation_failure",
"pattern": "[a-z]+[a-z_]*[a-z]+"
},
"message": {
"type": "string",
"description": "descriptive error message for debugging"
},
"moreInfo": {
"type": "string",
"format": "uri",
"description": "link to documentation to investigate further and finding support"
},
"details": {
"type": "array",
"description": "list of problems causing this error",
"items": {
"$schema": "http://json-schema.org/draft-04/schema#",
"title": "errorDetail",
"description": "schema for specific error cause",
"type": "object",
"properties": {
"field": {
"type": "string",
"description": "a bean notation expression specifying the element in request data causing the error, eg product.variants[3].name, this can be empty if violation was not field specific"
},
"type": {
"type": "string",
"description": "classification of the error detail type, lower case with underscore eg missing_value, this value must be always interpreted in context of the general error type.",
"pattern": "[a-z]+[a-z_]*[a-z]+"
},
"message": {
"type": "string",
"description": "descriptive error detail message for debugging"
},
"moreInfo": {
"type": "string",
"format": "uri",
"description": "link to documentation to investigate further and finding support for error detail"
}
},
"required": [
"type"
]
}
}
},
"required": [
"status",
"type"
]
}
Example:
{
"status": 403,
"message": "Given request does not have required scopes in access token. It is not authorized to perform this operation.",
"type": "insufficient_permissions"
}
HTTP status code 404
Identity provider with given ID was not found.
Body
Type: application/json
Schema:
errorMessageExample:
{
"status": 404,
"type": "element_non_existing",
"message": "Identity Provider with requested ID does not exist or belongs to the other organization.",
"moreInfo": "https://api.yaas.io/patterns/errortypes.html"
}
HTTP status code 412
Update failed. Object version determined by the ETag header value does not match any of the values listed in the If-Match header. Update the local copy of the resource to the latest version and resend the request.
Register a Custom Identity Provider
The process of registering a custom identity provider in YaaS consists of three basic steps:
Get the registration meta-data from the OAuth2 service
To get the meta-data required to register a custom identity provider in YaaS, you must to call the /registration-metadata endpoint of the Identity service.
This is a sample request to the /registration-metadata endpoint. It is an open resource, which means that you don't have to include an access token when you call this endpoint.
curl -X GET "http://api.eu.yaas.io/hybris/identity/v1/registration-metadata"The response includes an array of redirectURIs and an array of postLogoutRedirectURIs. To ensure that you use up-to-date information, call the
/registration-metadata endpoint every time you register a new custom identity provider for your organization.Create a client for your identity provider and obtain the client ID and client secret
Create a new client in your custom identity provider. Use the meta-data you obtained from the/registration-metadata endpoint.Get the client ID and client secret from the newly created client. You need this information to register your custom identity provider in YaaS.
Register your custom identity provider in the Identity service
To register your custom identity provider, you must call the /providers endpoint of the Identity service. The request must include an access token issued for the organization for which you want to register the custom identity provider. The token must also include the hybris.org_manage scope.
Pass the OpenID configuration, client ID and client secret you obtained from the client you created in the previous step. Additionally, include the display name of your custom identity provider.
This is a sample identity provider registration request to the/providers endpoint. Line breaks are added for better readability.curl -X POST "http://api.eu.yaas.io/hybris/identity/v1/providers" \
-H 'Authorization: Bearer ACCESS_TOKEN_HERE \
-H 'Content-Type: application/json' \
-d '{"displayName":"My IDprovider","credentials":{"clientId":"a9883977-97e3-44d9-a4cb-7c2df0f7a267","clientSecret":"2loftph991j058u3"}, \
"openidConfiguration":{"issuer":"https://someorg.io","authorization_endpoint":"https://someorg.io/authorize", \
"token_endpoint":"https://someorg.io/token","jwks_uri":"https://someorg.io/jwks"}}' \
The successful response from the Identity service confirms the registration of the custom identity provider and returns the alpha-numeric ID of the custom identity provider, as well as a link to the registered provider. This is a sample code 201 response from the service:
{"id":"594b8c8176b391a1c5c6344a","link":"https://api.eu.yaas.io/hybris/identity/v1/providers/594b8c8176b391a1c5c6344a"}Use the custom identity provider
After you successfully register your custom identity provider in the Identity service, you can use it with the Implicit Grant and the Authorization Code Grant authorization flows available in YaaS.
For more information about the authorization flows available in YaaS, see the Grants section of the OAuth2 service documentation.
To use your custom identity provider, provide the ID you received in the code 201 successful response from the Identity service as the value of the hybris_id_provider parameter in the request to the OAuth2 service.This example shows an Authorization Code Grant flow access token request that uses a custom identity provider:
curl -i -X GET 'https://api.eu.yaas.io/hybris/oauth2/v1/authorize?response_type=code&client_id=CLIENT_ID&scope=SCOPE_NAME&state=STATE&hybris_id_provider=724987custom_idp_id09u'If you find any information that is unclear or incorrect, please let us know so that we can improve the Dev Portal content.
Use our private help channel. Receive updates over email and contact our specialists directly.
If you need more information about this topic, visit hybris Experts to post your own question and interact with our community and experts.