Overview
SAML2 Adapter is an essential YaaS service that allows you to register a custom SAML 2.0 identity provider for your organization.
You can register multiple identity providers for a single organization. The SAML 2.0 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
/metadata
Get the YaaS SAML 2.0 Adapter metadata.
/metadata
Get the YaaS SAML 2.0 Adapter metadata. Register this metadata as a Service Provider in the SAML 2.0 Identity Provider to establish successful communication between the SAML 2.0 Identity Provider and the YaaS SAML2 Adapter service.
get /metadata
Get the YaaS SAML 2.0 Adapter metadata. Register this metadata as a Service Provider in the SAML 2.0 Identity Provider to establish successful communication between the SAML 2.0 Identity Provider and the YaaS SAML2 Adapter service.
HTTP status code 200
YaaS SAML 2.0 Adapter service metadata to be registered at SAML 2.0 Identity Provider as a Service Provider.
Body
Type: application/json
Schema:
{
"$schema": "http://json-schema.org/draft-04/schema",
"description": "Object metadata",
"type": "object",
"required": [
"issuer",
"assertionConsumerService",
"singleLogoutEndpoint",
"x509Certificate"
],
"properties": {
"issuer": {
"description": "The identifier of authentication requests issuer. Corresponds to application name in case of SAP Cloud Identity configuration",
"type": "string"
},
"assertionConsumerService": {
"description": "Object defining Service Provider configuration used for handling authentication responses",
"type": "object",
"properties": {
"location": {
"type": "string",
"description": "The URL of the service provider assertion consumer service endpoint on which will receive responses from Identity Provider service."
},
"binding": {
"type": "string",
"description": "Protocol binding type",
"enum": [
"HTTP-Post"
]
}
}
},
"singleLogoutEndpoint": {
"description": "Object defining Service Provider configuration used for handling single logout messages",
"type": "object",
"properties": {
"location": {
"type": "string",
"description": "The URL of the service provider single logout endpoint on which will receive logout messages from Identity Provider service."
},
"binding": {
"type": "string",
"description": "Protocol binding type",
"enum": [
"HTTP-Redirect"
]
}
}
},
"x509Certificate": {
"description": "A public certificate used by Identity Provider for verification of signed requests.",
"type": "string"
}
}
}
Example:
{
"issuer": "yaas.accounts.sap.com",
"assertionConsumerService": {
"location": "https://api.eu.yaas.io/hybris/saml2-adapter/v1/auth/callback",
"binding": "HTTP-Post"
},
"singleLogoutEndpoint": {
"location": "https://api.eu.yaas.io/hybris/sap-authentication/v1/end_session/slo_callback",
"binding": "HTTP-Redirect"
},
"x509Certificate": "IICHTCCAYagAwIBAgIETKTcJjANBgkqhkiG9w0BAQUFADBTMQswCQYDVQQGEwJEAH8SCNXS73N2SBxMGQmVybGluMQwwCgYDVQQKEwNTQVAxDjAMBgNVBAsTBVdlYkttMRUwEwYDVQQDEwxE"
}
/authorize
THIS IS AN INTERNAL ENDPOINT
The OAuth2 Authorization Endpoint is used to authenticate user in SAP Cloud Platform Identity Authentication and obtain an authorization code.
For more information, see the OAuth 2.0 specification (rfc6749#section-3.1) and Getting Started tutorial.
/authorize
Starts the authorization procedure with the parameters specified in the URL query.
get /authorize
Starts the authorization procedure with the parameters specified in the URL query.
Headers
- content-type: (string)
Format of sent data. If provided, it MUST be set to 'application/x-www-form-urlencoded'.
Query Parameters
- response_type: required (string)
OAuth 2.0 Response Type value that determines the authorization processing flow to be used, including what parameters are returned from the endpoints used.
Since this service supports only fetching id tokens using Authorization Code Grant, this value MUST becode. - client_id: required (string)
This is the client identifier. Client have to be registered in Authentication Service before this service could be used. Dynamic registration is not supported.
For more information, see the OAuth 2.0 specification (rfc6749#section-2.2). - redirect_uri: required (string)
This URL is used as a callback after a successful authentication and authorization grant to redirect the authorization code.
For security reasons, TLS should be used for redirect URIs.
For more information, see the OAuth 2.0 specification (rfc6749#section-3.1.2). - scope: required (string)
This lists the requested scopes of the access.
Since this service supports only the OpenID Connect Authentication Request, openid scope MUST be requested.
The predefined scopes are:- openid - This scope means that request should be treated as OpenID Connect Authentication Request. Client MUST request for this scope.
- email - Scope should be included if id token should contain email claim.
For more information, see the OpenID Connect Authentication Request and OAuth 2.0 specification (rfc6749#section-3.3).
Example:
openid email
- openid - This scope means that request should be treated as OpenID Connect Authentication Request. Client MUST request for this scope.
- state: (string)
RECOMMENDED. This is an opaque value used by the client to maintain the state between the request and the redirect.
This value is included when redirecting the user agent back to the client.
The parameter should be used to prevent cross-site request forgery as described in the OAuth 2.0 specification (rfc6749#section-10.12).Example:
security_token%3D9F2a3290Daa126P%26custom_state%3Dhttps://hybris.com/index.html
- id_token_hint: (string)
This value is used in subsequent requests for the id token (the actual ID token that was received in the previous request).
Could be used for SSO and it allows to issue id token with new scopes without Login prompt. - nonce: required (string)
This value is used to prevent replay attacks when using id token. It must have sufficient entropy.
- hybris-session-id: (string)
This is the session identifier. It is generated if not passed.
- display: (string)
This value specifies how the Authentication Service displays the sign in page to the end user.
The supported value is:- page - displays a standalone sign-in page If you don't specify this value, it is set to default (page).
Example:
page
HTTP status code 200
The authentication page.
HTTP status code 302
The redirection to the redirect_uri.
Headers
- location: required (string)
The location equals to the redirect_uri with the following parameters in the URL query:
- If the authentication succeed:
- code - This is the authorization code issued by the Authentication Service. Client should exchange this code for id token using /token endpoint. Code is valid for 1 minute and can be used only once.
- state - This is the exact value received from the client if it was specified in the request "state" parameter.
- If the resource owner denies the access request, or if the request fails for reasons other than a missing or invalid redirection URI:
- error - This is a single ASCII error code from the following:
- invalid_request - The request is missing a required parameter, includes an invalid parameter value, includes a parameter more than once, or is otherwise malformed.
- unauthorized_client - The client is not authorized to request an authorization code using this method.
- access_denied - The resource owner or Authentication Service denied the request.
- unsupported_response_type - The Authentication Service does not support obtaining an id token using this method.
- invalid_scope - The requested scope is invalid, unknown, or malformed.
- server_error - The Authentication Service encountered an unexpected condition that prevented it from completing the request.
- temporarily_unavailable - The Authentication Service is currently unable to handle the request due to a temporary overloading or maintenance of the server.
- error_description - This is a human-readable ASCII text line providing additional information that is used to assist the client developer in understanding the returned error.
- error_uri - This is a URI identifying a human-readable webpage with information about the error that is used to provide the client developer with additional information about the error.
- state - This is the exact value received from the client if it was specified in the request "state" parameter.
- error - This is a single ASCII error code from the following:
- If the authentication succeed:
HTTP status code 400
Bad request is returned if the parameter:
- client_id is missing (the redirect_uri cannot be verified and redirect URL is not found)
- client_id has an invalid value (the redirect_uri cannot be verified and redirect URL is not found)
- client_id is included in the request more than once
- redirect_uri is missing
- redirect_uri has invalid value
- redirect_uri is included in the request more than once
/token
THIS IS AN INTERNAL ENDPOINT
The OAuth2 Token Endpoint is used to obtain an ID token.
For more information, see the OAuth 2.0 specification (rfc6749#section-3.2) and Getting Started tutorial.
/token
Can be used to exchange authorization code for an ID token.
post /token
Can be used to exchange authorization code for an ID token.
Headers
- Authorization: required (string)
Provides the basic authorization. Used to authenticate the client.
Client id and secret should be used respectively as username and password. For more information, see the OAuth 2.0 specification (rfc6749#section-2.3.1).Example:
Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW
Body
Type: application/x-www-form-urlencoded
Form Parameters- grant_type: required (string)
The grant type of the request. The value MUST be set to
authorization_code.Example:
authorization_code
- code: required (string)
Authorization code issued with OpenID Connect Authentication Request.
Example:
SplxlOBeZQQYbYS6WxSbIA
- redirect_uri: required (string)
This URL is used as a callback after a successful authentication and authorization grant to redirect the id token.
For security reasons, TLS should be used for redirect URIs.
For more information, see the OAuth 2.0 specification (rfc6749#section-3.1.2).Example:
http://localhost:3000
HTTP status code 200
Body
Type: application/json
Example:
{
"token_type": "Bearer",
"id_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6IjFlOWdkazcifQ.ewogImlzc
yI6ICJodHRwOi8vc2VydmVyLmV4YW1wbGUuY29tIiwKICJzdWIiOiAiMjQ4Mjg5
NzYxMDAxIiwKICJhdWQiOiAiczZCaGRSa3F0MyIsCiAibm9uY2UiOiAibi0wUzZ
fV3pBMk1qIiwKICJleHAiOiAxMzExMjgxOTcwLAogImlhdCI6IDEzMTEyODA5Nz
AKfQ.ggW8hZ1EuVLuxNuuIJKX_V8a_OMXzR0EHR9R6jgdqrOOF4daGU96Sr_P6q
Jp6IcmD3HP99Obi1PRs-cwh3LO-p146waJ8IhehcwL7F09JdijmBqkvPeB2T9CJ
NqeGpe-gccMg4vfKjkM8FcGvnzZUN4_KSP0aAp1tOJ1zZwgjxqGByKHiOtX7Tpd
QyHE5lcMiKPXfEIQILVq0pc_E2DzL7emopWoaoZTF_m0_N0YzFC6g6EJbOEoRoS
K5hoDalrcvRYLSrQAZZKflyuVCyixEoV9GfNQC3_osjzw2PAithfubEEBLuVVk4
XUVrWOLrLl0nx7RkKU8NXNHq-rvKMzqg"
}
HTTP status code 400
The bad request error is returned if:
- grant_type is missing or has an invalid value
- used invalid scope
Body
Type: application/json
Example:
{
"error": "invalid_request",
"error_description": "Invalid authorization code.",
"error_uri": "https://api.yaas.io/patterns/errortypes.html"
}
HTTP status code 401
Unauthorized returned when:
- The Authorization header is missing or invalid
Body
Type: application/json
Example:
{
"error": "invalid_client",
"error_description": "Invalid credentials."
"error_url": "https://api.yaas.io/patterns/errortypes.html"
}
/identity-providers
Use this endpoint to register and manage SAML 2.0 Identity Providers for your organization.
/identity-providers
Use this endpoint to get a list of the SAML 2.0 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.
Use this endpoint to register a new SAML 2.0 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 /identity-providers
Use this endpoint to get a list of the SAML 2.0 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 SAML 2.0 Identity Providers registerd for your organization has been successfully retireved.
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 **YaaS** (sorted ascending by the display name).",
"properties": {
"projects": {
"description": "List of the **Identity Provider**'s.",
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"displayName"
],
"properties": {
"id": {
"description": "Identifier of the **Identity Provider** in **YaaS**.",
"type": "string"
},
"displayName": {
"description": "Display name of the **Identity Provider**.",
"type": "string"
}
}
}
}
}
}
Example:
[
{
"id": "15bca5db-ff30-41cc-b514-7e83d93ec8d9",
"displayName": "Production IP"
},
{
"id": "4dd154cd-5d60-4575-a36d-738cf05f938d",
"displayName": "Test IP"
}
]
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 /identity-providers
Use this endpoint to register a new SAML 2.0 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",
"singleSignOnEndpoint",
"singleLogoutEndpoint"
],
"properties": {
"displayName": {
"description": "Display name of the Identity Provider.",
"type": "string"
},
"singleSignOnService": {
"description": "Object defining Identity Provider configuration used for handling authentication",
"type": "object",
"properties": {
"location": {
"type": "string",
"description": "The URL of the Identity Provider single sign on endpoint on which will receive authentication requests from Service Providers."
},
"binding": {
"type": "string",
"description": "Protocol binding type",
"enum": [
"HTTP-Post"
]
}
}
},
"singleLogoutService": {
"description": "Object defining Identity Provider configuration used for handling single logout messages",
"type": "object",
"properties": {
"location": {
"type": "string",
"description": "The URL of the Identity Provider single logout endpoint on which will receive logout requests from Service Providers."
},
"binding": {
"type": "string",
"description": "Protocol binding type",
"enum": [
"HTTP-Redirect"
]
}
}
},
"x509Certificate": {
"description": "Identity Provider's public certificate used by Service Providers for verification of signed responses.",
"type": "string"
}
}
}
Example:
{
"displayName": "my-id-provider",
"singleSignOnService": {
"location": "https://accounts.sap.com/saml2/idp/sso/accounts.sap.com",
"binding": "HTTP-Post"
},
"singleLogoutService": {
"location": "https://accounts.sap.com/saml2/idp/slo/accounts.sap.com",
"binding": "HTTP-Redirect"
},
"x509Certificate": "IICHTCCAYagAwIBAgIETKTcJjANBgkqhkiG9w0BAQUFADBTMQswCQYDVQQGEwJEAH8SCNXS73N2SBxMGQmVybGluMQwwCgYDVQQKEwNTQVAxDjAMBgNVBAsTBVdlYkttMRUwEwYDVQQDEwxE"
}
HTTP status code 201
SAML 2.0 Identity Provider hase 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/sap-authentication/v1/identity-providers/15bca5db-ff30-41cc-b514-7e83d93ec8d9"
}
HTTP status code 400
Request payload did not pass the validation process.
Body
Type: application/json
Schema:
errorMessageExample:
{
"status": 400,
"type": "validation_violation",
"message": "Display name 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"
}
/identity-providers/{id}
Use this endpoint to fetch information about the SAML 2.0 Identity Provider with the specified ID.
Security/Access Control: To access this method, an access token must be issued for the requested organization and have the hybris.org_manage scope.
Use this endpoint to update the SAML 2.0 Identity Provider information.
Security/Access Control: To access this method, an access token must be issued for the requested organization, and have the hybris.org_manage scope.
Use this endpoint to delete the SAML 2.0 Identity Provider with the specified ID.
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 /identity-providers/{id}
Use this endpoint to fetch information about the SAML 2.0 Identity Provider with the specified ID.
Security/Access Control: To access this method, an access token must be issued for the requested organization 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
HTTP status code 200
Information about the requested SAML 2.0 Identity Provider retrieved successfully.
Body
Type: application/json
Schema:
{
"$schema": "http://json-schema.org/draft-04/schema",
"type": "object",
"title": "Payload for the new **Identity Provider**.",
"required": [
"id",
"displayName",
"singleSignOnEndpoint",
"singleLogoutEndpoint"
],
"properties": {
"id": {
"description": "ID of the Identity Provider in YaaS.",
"type": "string"
},
"displayName": {
"description": "Display name of the Identity Provider.",
"type": "string"
},
"singleSignOnService": {
"description": "Object defining Identity Provider configuration used for handling authentication",
"type": "object",
"properties": {
"location": {
"type": "string",
"description": "The URL of the Identity Provider single sign on endpoint on which will receive authentication requests from Service Providers."
},
"binding": {
"type": "string",
"description": "Protocol binding type",
"enum": [
"HTTP-Post"
]
}
}
},
"singleLogoutService": {
"description": "Object defining Identity Provider configuration used for handling single logout messages",
"type": "object",
"properties": {
"location": {
"type": "string",
"description": "The URL of the Identity Provider single logout endpoint on which will receive logout requests from Service Providers."
},
"binding": {
"type": "string",
"description": "Protocol binding type",
"enum": [
"HTTP-Post"
]
}
}
},
"x509Certificate": {
"description": "Identity Provider's public certificate used by Service Providers for verification of signed responses.",
"type": "string"
}
}
}
Example:
{
"id": "2mfoewpoj32pf32",
"displayName": "my-id-provider",
"singleSignOnService": {
"location": "https://accounts.sap.com/saml2/idp/sso/accounts.sap.com",
"binding": "HTTP-Post"
},
"singleLogoutService": {
"location": "https://accounts.sap.com/saml2/idp/slo/accounts.sap.com",
"binding": "HTTP-Redirect"
},
"x509Certificate": "IICHTCCAYagAwIBAgIETKTcJjANBgkqhkiG9w0BAQUFADBTMQswCQYDVQQGEwJEAH8SCNXS73N2SBxMGQmVybGluMQwwCgYDVQQKEwNTQVAxDjAMBgNVBAsTBVdlYkttMRUwEwYDVQQDEwxE"
}
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 SAML 2.0 Identity Provider with the specified ID.
Body
Type: application/json
Schema:
errorMessageExample:
{
"status": 404,
"type": "element_non_existing",
"message": "Identity Provider with requested ID does not exist or belongs to a different organization.",
"moreInfo": "https://api.yaas.io/patterns/errortypes.html"
}
put /identity-providers/{id}
Use this endpoint to update the SAML 2.0 Identity Provider information.
Security/Access Control: To access this method, an access token must be issued for the requested organization, 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
Body
Type: application/json
Schema:
{
"$schema": "http://json-schema.org/draft-04/schema",
"type": "object",
"title": "Payload for the new **Identity Provider**.",
"required": [
"displayName",
"singleSignOnEndpoint",
"singleLogoutEndpoint"
],
"properties": {
"displayName": {
"description": "Display name of the Identity Provider.",
"type": "string"
},
"singleSignOnService": {
"description": "Object defining Identity Provider configuration used for handling authentication",
"type": "object",
"properties": {
"location": {
"type": "string",
"description": "The URL of the Identity Provider single sign on endpoint on which will receive authentication requests from Service Providers."
},
"binding": {
"type": "string",
"description": "Protocol binding type",
"enum": [
"HTTP-Post"
]
}
}
},
"singleLogoutService": {
"description": "Object defining Identity Provider configuration used for handling single logout messages",
"type": "object",
"properties": {
"location": {
"type": "string",
"description": "The URL of the Identity Provider single logout endpoint on which will receive logout requests from Service Providers."
},
"binding": {
"type": "string",
"description": "Protocol binding type",
"enum": [
"HTTP-Redirect"
]
}
}
},
"x509Certificate": {
"description": "Identity Provider's public certificate used by Service Providers for verification of signed responses.",
"type": "string"
}
}
}
Example:
{
"displayName": "my-id-provider",
"singleSignOnService": {
"location": "https://accounts.sap.com/saml2/idp/sso/accounts.sap.com",
"binding": "HTTP-Post"
},
"singleLogoutService": {
"location": "https://accounts.sap.com/saml2/idp/slo/accounts.sap.com",
"binding": "HTTP-Redirect"
},
"x509Certificate": "IICHTCCAYagAwIBAgIETKTcJjANBgkqhkiG9w0BAQUFADBTMQswCQYDVQQGEwJEAH8SCNXS73N2SBxMGQmVybGluMQwwCgYDVQQKEwNTQVAxDjAMBgNVBAsTBVdlYkttMRUwEwYDVQQDEwxE"
}
HTTP status code 204
Information about the requested SAML 2.0 Identity Provider has been successfully updated.
HTTP status code 400
Request payload did not pass validation process.
Body
Type: application/json
Schema:
errorMessageExample:
{
"status": 400,
"type": "validation_violation",
"message": "Display name 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
There is no SAML 2.0 Identity Provider with the specified ID.
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"
}
delete /identity-providers/{id}
Use this endpoint to delete the SAML 2.0 Identity Provider with the specified ID.
Security/Access Control: To access this method, an access token must be issued for the requested organization, 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
HTTP status code 204
The SAML 2.0 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
There is no SAML 2.0 Identity Provider with the specified ID.
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"
}Register a custom SAML 2.0 identity provider
The process of registering a custom SAML 2.0 identity provider in YaaS consists of two basic steps:
- Get the YaaS OAuth2 service meta-data and register it in your SAML 2.0 identity provider.
- Register your SAML 2.0 identity provider in the SAML2 Adapter service.
Get the registration meta-data from the OAuth2 service
To get the meta-data required to register a custom SAML 2.0 identity provider in YaaS, you must call the `/metadata` endpoint of the SAML2 Adapter service.
This is a sample request to the `/metadata` endpoint. It is a public 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/saml2-adapter/v1/metadata"The response contains the X.509 certificate of the OAuth2 service, as well as the Assertion Consumer Service location URL and the single logout endpoint URL. To ensure that you use up-to-date information, call the `/metadata` endpoint every time you register a new custom SAML 2.0 identity provider for your organization.
Register your custom SAML 2.0 identity provider
To register your custom SAML 2.0 identity provider, you must call the /identity-providers endpoint of the SAML2 Adapter service. The request must include an access token issued for the organization for which you want to register the custom SAML 2.0 identity provider. The token must also include the hybris.org_manage scope.
Define the display name of the custom SAML 2.0 identity provider, specify the URL of the endpoint which the OAuth2 serivce must contact to get a SAML authentication assertion (**SingleSignOnService**), logout endpoint URL (**singleLogoutService**), as well as the X.509 certificate of your identity provider.
This is a sample SAML 2.0 identity provider registration request to the/identity-providers endpoint. Line breaks are added for better readability.curl -X POST "http://api.eu.yaas.io/hybris/saml2-adapter/v1/identity-providers" \
-H 'Authorization: Bearer ACCESS_TOKEN_HERE \
-H 'Content-Type: application/json' \
-d '{"displayName":"My IDprovider","singleSignOnService":{"location":"https://accounts.sap.com/saml2/idp/sso/accounts.sap.com","binding":"HTTP-Post"}, \
"singleLogoutService":{"location":"https://accounts.sap.com/saml2/idp/slo/accounts.sap.com","binding":"HTTP-Redirect"}, \
"x509Certificate":"98127498137randomcertificatestring238402480"}'
Use the custom SAML 2.0 identity provider
After you successfully register your custom SAML 2.0 identity provider, you can use it with the Implicit Grant and the Authorization Code Grant authorization flows available in YaaS.
To use your custom SAML 2.0 identity provider, use the ID you received in the successful registration response from the SAML2 Adapter 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 SAML 2.0 identity provider:
curl -i -X GET '<a href="https://api.eu.yaas.io/hybris/oauth2/v1/authorize?response_type=code&client_id=CLIENT_ID&scope=SCOPE_NAME&state=STATE&hybris_id_provider=81_customsaml2idp0&577$45564">https://api.eu.yaas.io/hybris/oauth2/v1/authorize?response_type=code&client_id=CLIENT_ID&scope=SCOPE_NAME&state=STATE&hybris_id_provider=81_customsaml2idp0&577$45564</a>'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.