Configure Single Sign-On for the BUI Login

Use these commands to enable Single Sign-On (SSO) for authentication to the browser user interface (BUI). SSO configuration is part of the HTTPS service. The SAML Service Provider (SP) registration metadata is a child resource of the HTTPS service.

Example 16-5 List HTTPS Single Sign-On Configuration

Example Request:

GET /api/service/v2/services/https HTTP/1.1
Host: zfs-storage.example.com:215
X-Auth-Session: uerqghq84vbdmRFN2bY4xdxHHC56q4

Example Result:

{
    "service": {
        "href": "/api/service/v2/services/https",
        "<status>": "online",
        "tls_version": [
            "TLSv1.2",
            "TLSv1.3"
        ],
        "ciphers": [
            "TLS_AES_256_GCM_SHA384",
            "TLS_AES_128_GCM_SHA256",
            "ECDHE-ECDSA-AES128-GCM-SHA256",
            "ECDHE-ECDSA-AES256-GCM-SHA384",
            "ECDHE-RSA-AES128-GCM-SHA256",
            "ECDHE-RSA-AES256-GCM-SHA384",
            "ECDHE-ECDSA-AES256-CCM",
            "ECDHE-ECDSA-AES128-CCM"
        ],
        "permit_root_login": true,
        "session_timeout": 900,
        "hsts_enable": false,
        "hsts_max_age": 63072000,
        "sso_enabled": true,
        "sso_attr_ldapuser": "guid",
        "sso_sp_cert": "7efb8d82-bc09-4c93-9c56-c897ed8a1cfb",
        "sso_idp": [
            "entityID=https://idcs-unique-id.identity-test.oraclecloud.com/fed,validUntil=2027-06-27T21:59:13Z"
        ],
        "sso_node_fqdn": "node-fqdn.example.com",
        "sso_peer_fqdn": "peer-fqdn.example.com",
        "registration": {
            "href": "/api/service/v2/services/https/registration",
            "node_entity_id": "https://node-fqdn.example.com:215",
            "node_acs_url": "https://node-fqdn.example.com:215/sso/saml/postResponse",
            "peer_entity_id": "https://peer-fqdn.example.com:215",
            "peer_acs_url": "https://peer-fqdn.example.com:215/sso/saml/postResponse",
            "certificate": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----\n"
        },
        "7efb8d82-bc09-4c93-9c56-c897ed8a1cfb": {
            "href": "/api/service/v2/services/https/7efb8d82-bc09-4c93-9c56-c897ed8a1cfb",
            "uuid": "7efb8d82-bc09-4c93-9c56-c897ed8a1cfb",
            "type": "cert",
            "subject_commonname": "peer-fqdn.example.com",
            "issuer_commonname": "peer-fqdn.example.com",
            "dns": [
                "peer-fqdn.example.com",
                "peer-hostname",
                "192.0.2.122"
            ],
            "ip": [
                "192.0.2.122"
            ],
            "uri": [
                "https://peer-fqdn.example.com:215",
                "https://peer-hostname:215",
                "https://192.0.2.122:215"
            ],
            "comment": "Automatically generated",
            "notbefore": "2006-02-15T18:00:00Z",
            "notafter": "2038-01-19T03:14:07Z",
            "serialnumber": "61:FC:2D:DE:00:00:00:02",
            "sha1fingerprint": "43:03:43:13:F3:C1:1C:C3:65:0E:7C:4B:0F:57:9E:0A:11:AA:C6:A5",
            "sha256fingerprint": "C8:E2:22:91:F2:A6:5D:76:49:5A:C5:58:17:2C:63:FE:73:AD:3E:A4:3E:B2:06:61:20:03:EA:61:0F:CA:81:F8",
            "key_type": "RSA",
            "key_bits": 2048
        }
    }
}

The response includes the system certificates, which are displayed after the registration resource. When enabling SSO, set the sso_sp_cert value to the UUID of the certificate you plan to use for securing IdP traffic.

Example 16-6 Upload Identity Provider Metadata

Use a POST request to upload the Identity Provider metadata file to the HTTPS service.

Example Request:

curl --user root:<password> -k \
  --data-binary @<idp-metadata.xml> \
  --header "Content-Type: application/octet-stream" \
  https://zfs-storage.example.com:215/api/service/v2/services/https/idp

On success, no response body is returned. On error, an error message can be returned.

Example 16-7 Enable HTTPS Single Sign-On

Example Request:

PUT /api/service/v2/services/https HTTP/1.1
Host: zfs-storage.example.com:215
X-Auth-Session: uerqghq84vbdmRFN2bY4xdxHHC56q4
Content-Type: application/json

{
    "sso_sp_cert": "7efb8d82-bc09-4c93-9c56-c897ed8a1cfb",
    "sso_node_fqdn": "node-fqdn.example.com",
    "sso_peer_fqdn": "peer-fqdn.example.com",
    "sso_enabled": true
}

Example Result:

{
    "service": {
        "href": "/api/service/v2/services/https",
        "<status>": "online",
        "tls_version": [
            "TLSv1.2",
            "TLSv1.3"
        ],
        "ciphers": [
            "TLS_AES_256_GCM_SHA384",
            "TLS_AES_128_GCM_SHA256",
            "ECDHE-ECDSA-AES128-GCM-SHA256",
            "ECDHE-ECDSA-AES256-GCM-SHA384",
            "ECDHE-RSA-AES128-GCM-SHA256",
            "ECDHE-RSA-AES256-GCM-SHA384",
            "ECDHE-ECDSA-AES256-CCM",
            "ECDHE-ECDSA-AES128-CCM"
        ],
        "permit_root_login": true,
        "session_timeout": 900,
        "hsts_enable": false,
        "hsts_max_age": 63072000,
        "sso_enabled": true,
        "sso_attr_ldapuser": "guid",
        "sso_sp_cert": "7efb8d82-bc09-4c93-9c56-c897ed8a1cfb",
        "sso_idp": [
            "entityID=https://idcs-unique-id.identity-test.oraclecloud.com/fed,validUntil=2027-06-27T21:59:13Z"
        ],
        "sso_node_fqdn": "node-fqdn.example.com",
        "sso_peer_fqdn": "peer-fqdn.example.com",
        "registration": {
            "href": "/api/service/v2/services/https/registration",
            "node_entity_id": "https://node-fqdn.example.com:215",
            "node_acs_url": "https://node-fqdn.example.com:215/sso/saml/postResponse",
            "peer_entity_id": "https://peer-fqdn.example.com:215",
            "peer_acs_url": "https://peer-fqdn.example.com:215/sso/saml/postResponse",
            "certificate": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----\n"
        },
        "e8b2bd8c-3eef-4c27-98f6-db1cd29827ba": {
            "href": "/api/service/v2/services/https/e8b2bd8c-3eef-4c27-98f6-db1cd29827ba",
            "uuid": "e8b2bd8c-3eef-4c27-98f6-db1cd29827ba",
            "type": "cert",
            "subject_commonname": "node-fqdn.example.com",
            "issuer_commonname": "node-fqdn.example.com",
            "dns": [
                "node-fqdn.example.com",
                "node-hostname",
                "192.0.2.165"
            ],
            "ip": [
                "192.0.2.165"
            ],
            "uri": [
                "https://node-fqdn.example.com:215",
                "https://node-hostname:215",
                "https://192.0.2.165:215"
            ],
            "comment": "Automatically generated",
            "notbefore": "2006-02-15T18:00:00Z",
            "notafter": "2038-01-19T03:14:07Z",
            "serialnumber": "61:FC:2D:DE:00:00:00:04",
            "sha1fingerprint": "21:A8:E6:FF:D7:14:6C:F0:9B:E7:5E:23:6D:53:5A:7E:86:9F:30:47",
            "sha256fingerprint": "49:ED:9F:78:B7:67:04:5B:09:37:24:89:F4:5A:C6:39:3B:82:D8:68:A5:9F:2C:71:D0:FF:27:26:7F:BD:F4:5E",
            "key_type": "RSA",
            "key_bits": 2048
        }
    }
}

Example 16-8 Modify HTTPS Single Sign-On Configuration

Example Request:

PUT /api/service/v2/services/https HTTP/1.1
Host: zfs-storage.example.com:215
X-Auth-Session: uerqghq84vbdmRFN2bY4xdxHHC56q4
Content-Type: application/json

{
    "sso_sp_cert": "7efb8d82-bc09-4c93-9c56-c897ed8a1cfb",
    "sso_node_fqdn": "new-node-fqdn.example.com",
    "sso_peer_fqdn": "new-peer-fqdn.example.com",
    "sso_enabled": true
}

The result includes the full HTTPS service object. This example shows only the relevant SSO properties.

Example Result:

{
    "service": {
        "href": "/api/service/v2/services/https",
        "<status>": "online",
        [...]
        "sso_enabled": true,
        "sso_attr_ldapuser": "guid",
        "sso_sp_cert": "7efb8d82-bc09-4c93-9c56-c897ed8a1cfb",
        "sso_idp": [
            "entityID=https://idcs-unique-id.identity-test.oraclecloud.com/fed,validUntil=2027-06-27T21:59:13Z"
        ],
        "sso_node_fqdn": "new-node-fqdn.example.com",
        "sso_peer_fqdn": "new-peer-fqdn.example.com",
        [...]
    }
}

Example 16-9 List Service Provider Registration Metadata

Use the registration child resource to list the SAML SP registration metadata for the HTTPS service.

Example Request:

GET /api/service/v2/services/https/registration HTTP/1.1
Host: zfs-storage.example.com:215
X-Auth-Session: uerqghq84vbdmRFN2bY4xdxHHC56q4

Example Result:

{
    "registration": {
        "href": "/api/service/v2/services/https/registration",
        "node_entity_id": "https://node-fqdn.example.com:215",
        "node_acs_url": "https://node-fqdn.example.com:215/sso/saml/postResponse",
        "peer_entity_id": "https://peer-fqdn.example.com:215",
        "peer_acs_url": "https://peer-fqdn.example.com:215/sso/saml/postResponse",
        "certificate": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----\n"
    }
}

Example 16-10 Disable HTTPS Single Sign-On

Example Request:

PUT /api/service/v2/services/https HTTP/1.1
Host: zfs-storage.example.com:215
X-Auth-Session: uerqghq84vbdmRFN2bY4xdxHHC56q4
Content-Type: application/json

{
    "sso_enabled": false
}

The result includes the full HTTPS service object. This example shows only the relevant SSO properties.

Example Result:

{
    "service": {
        "href": "/api/service/v2/services/https",
        "<status>": "online",
        [...]
        "sso_enabled": false,
        "sso_attr_ldapuser": "guid",
        "sso_sp_cert": "7efb8d82-bc09-4c93-9c56-c897ed8a1cfb",
        "sso_idp": [
            "entityID=https://idcs-unique-id.identity-test.oraclecloud.com/fed,validUntil=2027-06-27T21:59:13Z"
        ],
        "sso_node_fqdn": "node-fqdn.example.com",
        "sso_peer_fqdn": "peer-fqdn.example.com",
        [...]
    }
}