Custom domains
What is custom domains
To make the deployment available through a corporate URL, you might need to setup a custom domain. Domain customization allows you to use your organization domain instead of redirecting your consumers to the Cloud-IAM domain.
This will help you maintain consistency and give a frictionless experience to your consumers.
How to access to custom domains
To access custom domains feature, follow these steps:
- Open Cloud-IAM console
- Select the Keycloak deployment you want to configure.
- Click on
Configuration - Select
Custom Domains - Then select
Registerto start the configuration
How to configure classic custom domain
In this article, we will assume that the domain my-custom.domain.tld will serve requests from the deployment deployment.cloud-iam.com.
A CNAME entry must be created in the customer DNS registar with name my-custom.domain.tld that targets deployment.cloud-iam.com
DNS record recommendation for custom domains
If you plan to create my-custom.domain.tld and my-custom is a DNS zone under domain.tld, you should create an ALIAS record instead of a CNAME.
The ALIAS record must point to deployment.cloud-iam.com. make sure to include the trailing dot (.) to indicate the fully qualified domain name.
In the end-user point of view my-custom.domain.tld becomes an alias of deployment.cloud-iam.com.
The requests still go straight from the user's browser to the Cloud-IAM deployment without any additional server in the middle. Please note that the JWT token issuer (claim iss) will reflect your custom domain.
The requests are TLS encrypted end-to-end using a certificate generated via Let'sEncrypt. The generated certificates are short live certificates for security reasons. They are valid for 90 days and Cloud-IAM will automatically renew the certificates about 30 days before their expiration date.
Once the DNS entry has been properly configured, simply declare it through the Cloud-IAM console. This will trigger the certificate generation and installation in minutes.
How to configure a reverse proxy
In some cases, the traffic going to the deployment might need to be cached, filtered, analyzed, redirected or customized. This requires the customer to pass every requests through an active server (e.g. Nginx, Traefik, Envoy, Kong, Gravitee, ...) that acts as a reverse proxy.
In this article, we will assume that the domain my-custom.domain.tld will serve requests from the deployment deployment.cloud-iam.com.
Here is a simplified version of the Nginx configuration server that will handle requests on my-custom.domain.tld.
server {
server_name my-custom.domain.tld;
ssl_certificate /etc/.../certificate.crt;
ssl_certificate_key /etc/.../privkey.pem;
upstream api {
server deployment.cloud-iam.com:443;
keepalive 38;
}
location / {
proxy_pass https://api/;
}
}In this case, the server is added between the end-user and the Cloud-IAM cluster. As all the traffic passes through this server, this should be replicated horizontally and be reliable.
The TLS certificate for my-custom.domain.tld must be configured and renewed by the customer.
The requests are still TLS encrypted end-to-end.
You then need to declare the custom-domain in the Cloud-IAM Console, and precise the traffic if proxied to Cloud-IAM:
Avoid rate-limiting issues with proxy traffic
After configuration, since all traffic will appear to come from the proxy server in Cloud-IAM, this can trigger rate-limiting. To prevent this, add the reverse proxy gateway IP address to the deployment’s allowlist Logins rules to bypass rate-limiting.
How to configure a CDN
A CDN (like Cloudflare, AWS Cloudfront, ...) is a reverse proxy at scale with additional features such as intelligent filtering, caching, routing, ... This implies that the end-user requests are not directly routed to the Cloud-IAM cluster, but an additional server (company) interacts before proxying them to the cluster.
In this article, we will assume that the domain my-custom.domain.tld will serve requests from the deployment deployment.cloud-iam.com.
Cloud-IAM's deployments can be 'CDNifed'.
The CDN becomes responsible for managing the TLS certificate for my-custom.domain.tld. It must be configured to use a full encryption mode to ensure the requests are still encrypted end-to-end.
You then need to declare the custom-domain in the Cloud-IAM Console, and precise the traffic if proxied to Cloud-IAM:
Avoid rate-limiting issues with CDN traffic
After configuration, since all traffic will appear to come from the CDN in Cloud-IAM, this can trigger rate-limiting. To prevent this, add the CDN gateway IP address to the deployment’s allowlist Logins rules to bypass rate-limiting.
How to manage Extended Validation (EV) certificates
Cloud-IAM takes the responsibility of generating a valid TLS certificate for my-custom.domain.tld (via Let'sEncrypt). The generated certificates are Domain Validation.
Despite the type of validation does not impact the strength of security associated with the certificate, customers might want to use their own OV or EV certificates or simply manage the certificate lifecycle by their self. Cloud-IAM support the upload of customer certificates in place of the generated certificates.
Certificate Renewal Responsibility
Please note that when using your own certificates, it is the customer's responsibility to renew them before they expire.
If the customer wants to use their own certificate, they must provide them via the Cloud-IAM API or through Cloud-IAM console.
Cloud-IAM APIs
$ DOMAIN=sub.domain.tld
$ DEPLOYMENT_ID=00000000-0000-0000-000000000000
$ TOKEN=$( ... | jq -r .access_token )
$
$ curl -X PUT -H "Authorization: Bearer ${TOKEN}" -H "Content-Type: application/json" \
"https://api.cloud-iam.com/deployments/${DEPLOYMENT_ID}/custom-domains/${DOMAIN}" -d "{
\"certPem\": \"-----BEGIN CERTIFICATE-----\nMIIEHDC...\n-----END CERTIFICATE-----\n\",
\"chainPem\": \"-----BEGIN CERTIFICATE-----\nMIIEWDC...\n-----END CERTIFICATE-----\n-----BEGIN CERTIFICATE-----\nMIIDuzCC...\n-----END CERTIFICATE-----\n\",
\"fullChainPem\": \"-----BEGIN CERTIFICATE-----\nMIIEHDC...\n-----END CERTIFICATE-----\n-----BEGIN CERTIFICATE-----\nMIIEWDC...\n-----END CERTIFICATE-----\n-----BEGIN CERTIFICATE-----\nMIIDuzCC...\n-----END CERTIFICATE-----\n\",
\"privateKeyPem\": \"-----BEGIN PRIVATE KEY-----\nMIIEvQIBAD..\n-----END PRIVATE KEY-----\n",
\"privateKeyPassword\": \"00000000-00000000-00000000-00000000",
}"certPem: contains the X509 certificate for the domain in a PEM formatchainPem: contains the list of X509 certificates of the Certification Authority (in the order intermediate CA, Root)fullChainPem: contains the list of X509 certificates of the certificate of the domain and the Certification Authority (in the order domain certificate, intermediate CA, Root)privateKeyPem: contains the private key of the domain certificateprivateKeyPassword: contains an optional password used to cipher the private key of the domain certificate. Leave null if the private key is not protected
Cloud-IAM Console
By turning off the Certificate is managed by Cloud-IAM toggle, a form will appear for you to provide your custom certificate details.
