Single sign-on APIs
Use these APIs to configure single sign-on (SSO) in your IBM® Cloud Private cluster.
Both cluster administrator and team Administrator can access all SSO APIs.
To use these APIs, you must add an authorization header to your request. You need an access token to add to the authorization header. To obtain the access token, see Preparing to run component or management API commands.
<Cluster Master Host>:<Cluster Master API Port> are used to access the APIs. The parameters are defined in Master endpoints.
Enable SAML
- API version
- 1.0.0
- API URI components
-
- Scheme
HTTPS
- Host IP
Cluster Master Host
- Port number
Cluster Master API Port
- Path
/idmgmt/v1/saml/management
- Command
PUT
- Command output format
application/json
The sample curl command resembles the following code:
curl -v -k -X PUT --header 'Authorization: Bearer $ACCESS_TOKEN' \
--header 'Content-Type: application/json' -d '{"enable": true}' https://<Cluster Master Host>:<Cluster Master API Port>/idmgmt/v1/saml/management
The response resembles the following code:
* Trying 1.1.1.1...
* Connected to 1.1.1.1 (1.1.1.1) port 8443 (#0)
* found 148 certificates in /etc/ssl/certs/ca-certificates.crt
* found 594 certificates in /etc/ssl/certs
* ALPN, offering http/1.1
* SSL connection using TLS1.2 / ECDHE_RSA_AES_256_GCM_SHA384
.
.
* ALPN, server accepted to use http/1.1
> PUT /idmgmt/v1/saml/management HTTP/1.1
> Host: 1.1.1.1:8443
> User-Agent: curl/7.47.0
> Accept: */*
> Authorization: Bearer
.
.
> Content-Type: application/json
> Content-Length: 16
>
* upload completely sent off: 16 out of 16 bytes
.
.
* Connection #0 to host 1.1.1.1 left intact
Response:
---------
Configuration successful
root@rise1:~#
Export metadata
- API version
- 1.0.0
- API URI components
-
- Scheme
HTTPS
- Host IP
Cluster Master Host
- Port number
Cluster Master API Port
- Path
/idauth/ibm/saml20/defaultSP/samlmetadata
- Command
GET
- Command output format
application/json
Note: This API call downloads an IBM Cloud Private metadata file.
The sample curl command resembles the following code:
curl -k -v -X GET --header 'Authorization: Bearer $ACCESS_TOKEN'\
https://<Cluster Master Host>:<Cluster Master API Port>/idauth/ibm/saml20/defaultSP/samlmetadata
The sample response resembles the following code:
* Trying 2.2.2.2...
* Connected to 2.2.2.2 (2.2.2.2) port 8443 (#0)
* found 148 certificates in /etc/ssl/certs/ca-certificates.crt
* found 594 certificates in /etc/ssl/certs
* ALPN, offering http/1.1
* SSL connection using TLS1.2 / ECDHE_RSA_AES_256_GCM_SHA384
.
.
< HTTP/1.1 200 OK
.
.
< X-XSS-Protection: 1; mode=block
<
<?xml version="1.0" encoding="UTF-8"?><md:EntityDescriptor xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata" entityID="https://2.2.2.2:8443/ibm/saml20/defaultSP"><md:SPSSODescriptor AuthnRequestsSigned="true" WantAssertionsSigned="true" protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol"><md:KeyDescriptor use="signing"><ds:KeyInfo xmlns:ds="http://www.w3.org/2000/09/xmldsig#"><ds:X509Data><ds:X509Certificate>MIID9zCCAd8CCQCB/mzlEf0kfzANBgkqhkiG9w0BAQsFADBjMQswCQYDVQQGEwJVUzERMA8GA1UE
.
.
daqKQMlMr3xN9BAqmrUuFwKsrhz1uuJ/4v3iePDG5Qy4k4UVuOFiz1e5Tsakw72fGjk=</ds:X509Certificate></ds:X509Data>\
</ds:KeyInfo></md:KeyDescriptor><md:KeyDescriptor use="encryption"><ds:KeyInfo xmlns:ds="http://www.w3.org/2000/09/xmldsig#"><ds:X509Data><ds:X509Certificate>MIID9zCCAd8CCQCB/mzlEf0kfzANBgkqhkiG9w0BAQsFADBjMQswCQYDVQQGEwJVUzERMA8GA1UE
.
.
daqKQMlMr3xN9BAqmrUuFwKsrhz1uuJ/4v3iePDG5Qy4k4UVuOFiz1e5Tsakw72fGjk=</ds:X509Certificate></ds:X509Data>\
</ds:KeyInfo></md:KeyDescriptor><md:SingleLogoutService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="https://2.2.2.2:8443/ibm/saml20/defaultSP/slo"/><md:AssertionConsumerService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="https://2.2.2.2:8443/ibm/saml20/defaultSP/acs" index="0" isDefault="true"/></md:SPSSODescriptor></md:EntityDescriptor>root@rise1:~#
Import metadata
- API version
- 1.0.0
- API URI components
-
- Scheme
HTTPS
- Host IP
Cluster Master Host
- Port number
Cluster Master API Port
- Path
/idmgmt/v1/saml/upload
- Command
POST
- Command output format
application/json
Note: You use this API call to upload the metadata file that you received from your enterprise SAML server. File name in the example is samlidp2_IBM_metadata_CIS_STAGE.xml.
The sample curl command resembles the following code:
curl -v -k -X POST --header 'Authorization: Bearer $ACCESS_TOKEN' \
-F 'data=@samlidp2_IBM_metadata_CIS_STAGE.xml' https://<Cluster Master Host>:<Cluster Master API Port>/idmgmt/v1/saml/upload
The sample response resembles the following code:
* Trying 1.1.1.1...
* TCP_NODELAY set
.
.
* ALPN, offering http/1.1
* Cipher selection: ALL:!EXPORT:!EXPORT40:!EXPORT56:!aNULL:!LOW:!RC4:@STRENGTH
* successfully set certificate verify locations:
* CAfile: C:/Program Files/Git/mingw64/ssl/certs/ca-bundle.crt
CApath: none
* TLSv1.2 (OUT), TLS header, Certificate Status (22):
} [5 bytes data]
.
.
* SSL connection using TLSv1.2 / ECDHE-RSA-AES256-GCM-SHA384
* ALPN, server accepted to use http/1.1
* Server certificate:
.
.
> POST /idmgmt/v1/saml/upload HTTP/1.1
> Host: 1.1.1.1:8443
> User-Agent: curl/7.53.0
> Accept: */*
> Authorization: Bearer
.
.
> Content-Length: 5313
> Expect: 100-continue
> Content-Type: multipart/form-data; boundary=------------------------9ecb5200d6d7e5e6
.
.
< HTTP/1.1 200 OK
.
.
{ [31 bytes data]
100 5344 100 31 100 5313 1 275 0:00:31 0:00:19 0:00:12 0Metadata uploaded successfully.
Verify SSO configuration status
- API version
- 1.0.0
- API URI components
-
- Scheme
HTTPS
- Host IP
Cluster Master Host
- Port number
Cluster Master API Port
- Path
/idmgmt/v1/saml/status
- Command
GET
- Command output format
application/json
Any of the following responses is valid:
-
{"enable":true}
SAML is enabled and the metadata file is successfully uploaded. -
{"status":false,"description":["SAML Feature not enabled"]}
SAML is not enabled. -
{"status":false,"description":["IDP Metadata not uploaded"]}
SAML is enabled but the metadata file that you received from your enterprise SAML server is not uploaded. -
{"status":false,"description":["SAML Feature not enabled", "IDP Metadata not uploaded"]}
SAML is not enabled, or you did not upload the metadata file that you received from your enterprise SAML server.
The sample curl command resembles the following code:
curl -k -v -X GET --header 'Authorization: Bearer $ACCESS_TOKEN' https://<Cluster Master Host>:<Cluster Master API Port>/idmgmt/v1/saml/status
The sample response resembles the following code:
* Trying 2.2.2.2...
* Connected to 2.2.2.2 (2.2.2.2) port 8443 (#0)
* found 148 certificates in /etc/ssl/certs/ca-certificates.crt
* found 594 certificates in /etc/ssl/certs
* ALPN, offering http/1.1
* SSL connection using TLS1.2 / ECDHE_RSA_AES_256_GCM_SHA384
.
.
* ALPN, server accepted to use http/1.1
> GET /idmgmt/v1/saml/status HTTP/1.1
> Host: 2.2.2.2:8443
> User-Agent: curl/7.47.0
> Accept: */*
> Authorization: Bearer
.
.
< HTTP/1.1 200 OK
< Server: openresty/1.11.2.4
< Date: Tue, 24 Jul 2018 08:43:00 GMT
< Content-Type: text/html; charset=utf-8
< Content-Length: 16
< Connection: keep-alive
< Vary: Origin, Accept-Encoding
< Access-Control-Allow-Credentials: true
< X-XSS-Protection: 1; mode=block
< X-Frame-Options: SAMEORIGIN
< Strict-Transport-Security: max-age=15552000; includeSubDomains
< X-Download-Options: noopen
< X-Content-Type-Options: nosniff
< X-DNS-Prefetch-Control: off
< ETag: W/"10-H+tYev0PkZ4BjVuzAcmKAO7d1nc"
< X-Frame-Options: SAMEORIGIN
< X-Content-Type-Options: nosniff
< X-XSS-Protection: 1; mode=block
<
* Connection #0 to host 2.2.2.2 left intact
_Response:_
{"status":false,"description":["SAML Feature not enabled"]}
Disable SAML
- API version
- 1.0.0
- API URI components
-
- Scheme
HTTPS
- Host IP
Cluster Master Host
- Port number
Cluster Master API Port
- Path
/idmgmt/v1/saml/management
- Command
PUT
- Command output format
application/json
This API disables SAML and deletes the metadata file that was sent by your enterprise SAML server.
The sample curl command resembles the following code:
curl -v -k -X PUT --header 'Authorization: Bearer $ACCESS_TOKEN' --header 'Content-Type: application/json' \
-d '{"enable": false}' https://<Cluster Master Host>:<Cluster Master API Port>/idmgmt/v1/saml/management
The sample response resembles the following code:
* Trying 1.1.1.1...
* Connected to 1.1.1.1 (1.1.1.1) port 8443 (#0)
* found 148 certificates in /etc/ssl/certs/ca-certificates.crt
* found 594 certificates in /etc/ssl/certs
* ALPN, offering http/1.1
* SSL connection using TLS1.2 / ECDHE_RSA_AES_256_GCM_SHA384
.
.
* ALPN, server accepted to use http/1.1
> PUT /idmgmt/v1/saml/management HTTP/1.1
> Host: 1.1.1.1:8443
> User-Agent: curl/7.47.0
> Accept: */*
> Authorization: Bearer
.
.
> Content-Type: application/json
> Content-Length: 17
>
* upload completely sent off: 17 out of 17 bytes
< HTTP/1.1 200 OK
< Server: openresty/1.11.2.4
< Date: Sat, 04 Aug 2018 09:54:14 GMT
< Content-Type: text/html; charset=utf-8
< Content-Length: 24
< Connection: keep-alive
< Vary: Origin, Accept-Encoding
< Access-Control-Allow-Credentials: true
< X-XSS-Protection: 1; mode=block
< X-Frame-Options: SAMEORIGIN
< Strict-Transport-Security: max-age=15552000; includeSubDomains
< X-Download-Options: noopen
< X-Content-Type-Options: nosniff
< X-DNS-Prefetch-Control: off
< ETag: W/"18-Akebq37pOvmw0KQ/7FxMJOPs24g"
< X-Frame-Options: SAMEORIGIN
< X-Content-Type-Options: nosniff
< X-XSS-Protection: 1; mode=block
<
* Connection #0 to host 1.1.1.1 left intact
Configuration successfulroot@rise1:~#