User Authentication and Authorization (UAA) - Configuration Guide October 28, 2021
←
→
Page content transcription
If your browser does not render page correctly, please read the page content below
User Authentication and Authorization (UAA) Configuration Guide October 28, 2021
Legal Notice Copyright © 2021 DigiCert, Inc. All rights reserved. DigiCert and its logo are registered trademarks of DigiCert, Inc. Other names may be trademarks of their respective owners. The product described in this document is provided by DigiCert, Inc. and distributed under licenses restricting its use, copying, distribution, and decompilation/reverse engineering. No part of this document may be reproduced in any form by any means without prior written authorization of DigiCert, Inc. and its licensors, if any. THE DOCUMENTATION IS PROVIDED "AS IS" AND ALL EXPRESS OR IMPLIED CONDITIONS, REPRESENTATIONS AND WARRANTIES, INCLUDING ANY IMPLIED WARRANTY OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE OR NON-INFRINGEMENT, ARE DISCLAIMED, EXCEPT TO THE EXTENT THAT SUCH DISCLAIMERS ARE HELD TO BE LEGALLY INVALID. DIGICERT, INC. SHALL NOT BE LIABLE FOR INCIDENTAL OR CONSEQUENTIAL DAMAGES IN CONNECTION WITH THE FURNISHING, PERFORMANCE, OR USE OF THIS DOCUMENTATION. THE INFORMATION CONTAINED IN THIS DOCUMENTATION IS SUBJECT TO CHANGE WITHOUT NOTICE. The licensed software and documentation are deemed to be commercial computer software as defined in FAR 12.212 and subject to restricted rights as defined in FAR Section 52.227-19 "Commercial Computer Software - Restricted Rights" and DFARS 227.7202, "Rights in Commercial Computer Software or Commercial Computer Software Documentation", as applicable, and any successor regulations. Any use, modification, reproduction release, performance, display or disclosure of the licensed software and documentation by the U.S. Government shall be solely in accordance with the terms of this documentation. DigiCert, Inc. 2801 North Thanksgiving Way, Suite 500 Lehi, UT 84043 https://www.digicert.com/ pg. 2
DigiCert® PKI Platform -UAA Production Details Table of Contents INTRODUCTION ........................................................................................................................... 4 SUPPORTED BROWSERS AND PLATFORMS .............................................................................................. 4 SUPPORTED BROWSERS AND PLATFORMS FOR DIGICERT DESKTOP CLIENT ............................................................ 5 QUALIFIED CERTIFICATE TEMPLATES AND ENROLLMENT/AUTHENTICATION METHODS ....................................... 6 SAML 2.0 IDP REQUIREMENTS ........................................................................................................... 7 RESTRICTIONS ................................................................................................................................. 8 CONFIGURE A TEMPLATE FOR FEDERATED AUTHENTICATION ON PKI MANAGER .............................................. 9 CONFIGURING A TEMPLATE FOR FEDERATED AUTHENTICATION WITH MANUAL APPROVAL ON PKI MANAGER ................................................................................................................................. 11 CONFIGURING SAML VIA THE UAA ADMIN PORTAL ............................................................................... 11 HOW TO USE SP AND IDP-INITIATED FLOWS ............................................................................... 14 CERTIFICATE SPECIFIC ENROLLMENT LINKS............................................................................................. 14 SELF-SERVICE PORTAL ENROLLMENT LINKS ........................................................................................... 15 SINGLE SIGN-ON (SSO) PORTAL ........................................................................................................ 16 HOW TO ENROLL FOR A CERTIFICATE.......................................................................................... 17 BROWSER PKCS12 ENROLLMENT FLOW .............................................................................................. 17 CSR ENROLLMENT FLOW .................................................................................................................. 19 DIGICERT DESKTOP CLIENT ENROLLMENT FLOW ..................................................................................... 20 MANUAL APPROVAL ENROLLMENT FLOW ............................................................................................. 21 HOW TO MANAGE YOUR CERTIFICATE ........................................................................................ 24 ADDITIONAL INFORMATION ....................................................................................................... 25 KNOWN ISSUES .......................................................................................................................... 26 TROUBLESHOOTING ................................................................................................................... 26 pg. 3
DigiCert® PKI Platform -UAA Production Details
Introduction
Welcome to the DigiCert PKI Platform SAML 2.0 solution. This new capability allows
customers to leverage their SAML IdP as the Registration Authority for enrollment.
The solution supports both SP-initiated (Service Provider) and IdP-initiated (Identity
Provider) SAML flows. The following enrollment methods support the new federated
authentication capability:
• Browser PKCS12 - to support issuance of certificates in PKCS12 format
• CSR - to support issuance of Device and Server certificates
• DigiCert Desktop Client - to support issuance of user certificates. The DigiCert
Desktop Client enables private keys and CSRs to be generated on the client within
the browser’s native keystores and on supported hardware tokens.
Certificate profiles are configured within the PKI Manager portal. The corresponding
SAML configuration and attribute mappings for each profile are done in a new User
Authorization Agent (UAA) Admin portal.
Users enroll for their certificates from a new UAA user portal, Subject DN (SDN) and
Subject Alternative Name (SAN) values are populated according to their configuration,
using either attribute statements in the SAML assertion or values read from a CSR
provided during the certificate enrollment process.
Supported Browsers and Platforms
Portal Operating System Browser
UAA Admin • Chrome 94
• Windows 10
• Firefox 93
• macOS (10.14)
• Microsoft Edge
• macOS (10.15)
94 (Windows/Mac)
• Chrome 94
• Windows 10 • Firefox 93
• macOS (10.14 or later) • Microsoft Edge
UAA User • Linux (Ubuntu 18.04) 94(Windows/Mac)
• iOS 13 • Safari (13.1 or later on macOS)
• Android 9 (Pie) • Safari (13 on iOS 13)
• Chrome (69.0 on Android 9)
pg. 4
DigiCert® PKI Platform -UAA Production Details
Supported Browsers and Platforms for DigiCert Desktop Client
You can download the DigiCert Desktop Client for Windows and macOS by visiting this
URL:https://pki-ddc.symauth.com/desktopclient
UAA User Portal Operating System Browser
Using DigiCert Windows 10 • Microsoft Edge 94
Desktop Client • Chrome 94
• Firefox 93 1
macOS (10.14 or later) • Microsoft Edge 94
• Chrome 94
• Safari (13.1 or later)
• Firefox 93
1DigiCert Desktop Client supports Firefox (on Windows 10). However, keys and
certificates are stored on the Windows certificate store (not Firefox’s PKCS11
keystore). You can configure Firefox to access your Windows certificate store - see
the instructions on the below section.
Table 1 – DigiCert Desktop Client supported hardware tokens
Hardware token vendor Hardware token model
Gemalto • eToken 5100
• eToken 5110
• eToken 5300 a
a eToken 5300 cannot run alongside the DigiCert PKI Client software for Windows
machines.
Note: Other tokens may work, but have not been formally qualified by DigiCert.
The DigiCert Desktop Client installer for Windows does not require Administrator
permissions - it installs under the logged-in user context. For macOS, local
Administrator credentials are required to access the Keychain. However, the keys are
installed on the User Keychain (not System Keychain) and available to third party
application.
Enabling Windows Certificate Store for Firefox
Follow the below steps to enable Firefox (v72 or later) to read your certificates from
the Windows certificate store, which is what DigiCert Desktop Client makes use to
generate keys and install certificates:
1. Open your Firefox browser (v72 or later) on Windows 10.
pg. 5
DigiCert® PKI Platform -UAA Production Details
2. Type about:config at the address bar.
3. Click on the Accept the Risk and Continue button.
4. Search for security.osclientcerts.autoload and set it to true.
You will now be able to access all the certificates stored on the Windows certificate
store.
Policies can be specified using the “Group Policy templates on Windows” by an
Enterprise Administrator, where the above configuration can be automatically set by
default for all users.
Qualified Certificate Templates and enrollment/authentication
methods
Certificate Template Type Enrollment Method
Browser PKCS12
Client Authentication Standard DigiCert Desktop
Client
Browser PKCS12
S/MIME (Digital Signature only) Standard DigiCert Desktop
Client
pg. 6
DigiCert® PKI Platform -UAA Production Details
All Templates in Device and
Server Pool that support CSR
enrollment method, e.g.
• Generic Device Authentication
• Generic Server Standard CSR
• Private Server
• Domain Controller
• IPSec Authentication
Custom
Generic Device Authentication
(with Browser PKCS12 and (contact DigiCert support Browser PKCS12
Federated Auth) to have this template
added to your account)
Custom
Generic Server (with Browser (contact DigiCert support Browser PKCS12
PKCS12 and Federated Auth) to have this template
added to your account)
Certificate templates created with public CA is not supported.
SAML 2.0 IdP Requirements
DigiCert PKI Platform supports any SAML 2.0 compliant IdP.
To strengthen security, DigiCert requires the SAML Responses or the SAML Assertion
to be signed by the IdP. If both are signed, both signatures will be verified by DigiCert.
Portal URL Screenshot
PKI https://pki-
Manager manager.symauth.com/pki-
manager/
pg. 7
DigiCert® PKI Platform -UAA Production Details
UAA Admin https://pki-
uaa.symauth.com/adm/login
It is unique per Configuration -
UAA User you can get the “SAML SP
Endpoint URL” from “Add
Configuration” and “Edit
Configuration” page.
User Self- It is unique per Account. You
Service can get this URL from by
Portal clicking on the “Self-Service
(SSP) Portal” menu.
Restrictions
Portal Description
Administrators invited to another account in DigiCert PKI
Platform can only access their account within the UAA Admin
portal. They have no access to invited accounts in UAA Admin.
UAA Admin Certificate Profile with multiple Common Name attributes is
not supported.
Test Drive accounts are not supported for UAA (“Federated
Auth”).
pg. 8
DigiCert® PKI Platform -UAA Production Details
When selecting CSR as the source for dnsName attributes in a
SAN, if multiple dnsName values are provided within the CSR,
only the first value is included in the certificate. If multiple
UAA User
values are required, change the source of this attribute to "User
Input" so that they can be manually entered on a web form by
a user.
Configure a template for Federated Authentication on PKI
Manager
Steps Details
Login to PKI Manager admin URL: https://pki-manager.symauth.com/pki-
portal manager/
Generate REST API key and
make a note of the key value.
pg. 9
DigiCert® PKI Platform -UAA Production Details
For “Browser P12”:
1. Create a Client
Authentication/ S/MIME
(Digital Signature only)
certificate profile
2. Select Enrollment
method as “Browser
PKCS12”
For “CSR” enrollment:
1. Create a certificate
profile from Device and
Server certificate
templates that supports
CSR enrollment method.
2. Select Enrollment
method as “CSR”
For “DigiCert Desktop Client”
enrollment:
1. Create a certificate
profile from the “Client
Authentication” / S/MIME
(Digital Signature only)
template
2. Select Enrollment
method as “DigiCert
Desktop Client”
3. Select “Security device”
under Certificate store to
use hardware token.
When choosing a
hardware token, you can
select a specific DigiCert-
qualified token family to
be used. Currently,
DigiCert supports
Gemalto tokens only.
However, there is a
profile option to select
“Any” token, which will
allow testing and use of
other tokens, but not
formally qualified.
pg. 10DigiCert® PKI Platform -UAA Production Details
Configuring a template for Federated Authentication with
Manual Approval on PKI Manager
Steps Details
While creating the profile
with any supported
enrollment method, click
on Authentication method
(Federated Auth) and
check “Enable Manual
approval” check box.
Configuring SAML via the UAA Admin portal
Steps Details Note
Login to UAA
Admin portal
using the URL : https://pki-
same PKI uaa.symauth.com/adm/login
manager
admin
certificate.
You can get an API
Add API key
Key from PKI
Settings > Manager under
Account, add Tasks > Manage
API key click API Key menu
on Test to option
test
connectivity To change the API
Key on the UAA
to your
Admin portal click
account and
on the Clear mark
if successful,
at the right, add API
click Save to
Key. Click on Test
save the
and then Save.
configuration.
pg. 11DigiCert® PKI Platform -UAA Production Details
Add SAML
Certificate profiles
configuration:
displayed in the
Settings > drop-down list are
Add those that have
Configuration been configured
Select the with an
certificate authentication
profile from method of
the drop- Federated auth.
down provide
the Name and
Description
for your
SAML
configuration.
Under
Certificate
Issuance Issue Instantly:
Method generates an
encrypted PKCS12
Select the
certificate
required
protected with
issuance
service generated
method from
password.
the drop-
down list Note: Issue
Instantly will not be
supported for
Browser PKCS12
enrollment method,
if Manual approval
authentication is
used.
Download
certificate from
Self-Service Portal:
generates an
encrypted PKCS12
certificate
protected with a
password chosen
by the user.
pg. 12DigiCert® PKI Platform -UAA Production Details
Under SAML Use SP Metadata
Service and SP Certificate
Provider (SP) to configure your
section SAML IdP service.
Download
Metadata and
Download SP
Cert
Under SAML
Identity
Provider (IdP)
section
Enter SAML
IdP Endpoint
URL from
your IdP
configuration
and upload
IdP Metadata
Source values can
be:
Under
Certificate • SAML Subject –
SAML value of SAML
Attribute subject in
Mapping SAML assertion
section. • SAML attribute
Map source – value of
SAML attribute
for Seat Id
Important Note: in SAML
and Seat
assertion
Email. • The Seat Email is only used by • User Input –
"Manual approval" profiles and the needs to be
value can be mapped to any of the entered by the
four available sources below. user during
• The "User Input" source is not enrollment
available for the Seat Id mapping. • Certificate Field
–a
unique/mandat
ory/non-fixed
certificate field
configured
within the
profile that can
be used to
uniquely bind to
pg. 13DigiCert® PKI Platform -UAA Production Details
a Seat Id for
licensing
purposes
Source values can
be:
• SAML Subject –
value of SAML
subject in
SAML assertion
Under
Certificate • SAML attribute
SAML – value of
Attribute SAML attribute
Mapping in SAML
section. assertion
• User Input –
Map Source needs to be
for certificate entered by the
fields and user during
then Save. enrollment
• CSR – attribute
values are
retrieved from
the CSR (Server
and Device
certificate
templates only)
How to use SP and IdP-initiated flows
There are various ways to enroll for a certificate:
• Certificate specific enrollment links: Administrators can distribute enrollment links
that allow users to enroll for individual certificates.
• Self-Service Portal enrollment links: Administrators can publish a link to the Self-
Service Portal. After authenticating, users can enroll for one or more certificates.
• Single Sign-On (SSO) portal: Users can visit their SSO portal where they can have
links to either the DigiCert Self-Service Portal or links to enroll for individual
certificates.
Certificate specific enrollment links
Administrators can distribute specific certificate enrollment links to users by sharing
the URL listed under “SAML SP Endpoint URL” -> “Add Configuration”, or when editing
an existing/saved configuration, which will redirect users to the IdP for authentication:
pg. 14DigiCert® PKI Platform -UAA Production Details When users visit the UAA Self-Service Portal, they are presented with a single option for certificate enrollment. Self-Service Portal enrollment links Administrators can publish an enrollment link to the Self-Service Portal. After authenticating, users can enroll for one or more certificates. The configuration is carried out under the “Self-Service Portal” section: pg. 15
DigiCert® PKI Platform -UAA Production Details Here is an example SSP Portal showing multiple enrollment links associated to multiple SAML configurations: Single Sign-On (SSO) portal Users can visit their SSO portal where they can see links/applications to either the DigiCert Self-Service Portal or links to enroll for individual certificates. Here is a sample screenshot for the Okta Single Sign-On page users will see upon authenticating via an Okta IdP: pg. 16
DigiCert® PKI Platform -UAA Production Details
How to enroll for a certificate
UAA supports three enrollment flows:
• Browser PKCS12
• CSR
• DigiCert Desktop Client
• Manual Approval enrollment flow
The below sections summarize each enrollment flow.
Browser PKCS12 enrollment flow
Steps Details Notes
Navigate to Self-
Service Portal URL
and login using
your IdP
credentials
Click on Enroll
under Actions
column against the
Profile Name
configured.
When a SAML
For Certificate configuration is
Issuance Method set to "Issue
as Issue Instantly Instantly", the
The user is generated private
redirected to their key will be stored
SAML IDP for into the "Browser
authentication. Session Storage"
with encryption
pg. 17DigiCert® PKI Platform -UAA Production Details
They will see a during the
Confirmation enrollment
window displaying process. The
the password for issued certificate
the P12 file. will be
Clicking OK on the delivered/downlo
aded as a
Confirmation
PKCS#12 file. All
window copies the
key material will
password to the
be deleted when
clipboard and
closing the
automatically
browser session.
downloads the 1
PKCS12 file.
Use the password
on the clipboard to
install the
certificate on your
browser of choice.
When a SAML
For Certificate configuration is
Issuance Method set to "Download
as Download Certificate from
certificate from Self-Service
Self-Service Portal. Portal", the
Select a password generated private
to encrypt the key will be stored
PKCS12 file and into "Browser
click OK. Persistent
Storage" with
Click on Download
encryption during
to download the
the enrollment
PKCS12 file.
process. The
Click on Download issued certificate
to download the will be
certificate. Enter delivered/downlo
the password in aded as a
the Enter Password PKCS#12 file. All
pop up. the key material
and certificates
are stored into
"Browser
Persistent
Storage", which is
accessible after
closing the
browser session.
To delete the key
pg. 18DigiCert® PKI Platform -UAA Production Details
material from the
persistent
storage, click
"Revoke" or
"Remove" from
within the SSP
Portal. 1
Depending on the
configuration, the
user might see a
dialog box to enter
enrollment data
used to sign the
certificate.
1This is NOT a recovery/escrow service, where keys would be securely generated and
stored at the Cloud. In both flows above the generated private key is NEVER exposed
anywhere.
CSR enrollment flow
Steps Details Notes
Navigate to the
SSP URL and login
using your IdP
credentials
Click on Enroll
under Actions
column against the
Profile Name
configured.
Enter the requested Depending on the
data to complete configuration, the
the enrollment user might see a
process. dialog box to
enter enrollment
data used to sign
the certificate or
can be read from
pg. 19DigiCert® PKI Platform -UAA Production Details
within the
submitted CSR.
Enter the CSR Once submitted,
without PEM the certificate will
headers and click be issued and
on OK. delivered via a
PKCS7 file.
DigiCert Desktop Client enrollment flow
Steps Details Notes
Navigate to the
SSP URL and login
using your IdP
credentials
Click on Enroll
under Actions
column against the
Profile Name
configured.
If the system We currently
doesn't have support installers
DigiCert Desktop for Windows and
Client installed, the macOS
user will see a
platforms.
warning pop-up.
pg. 20DigiCert® PKI Platform -UAA Production Details
This is a portal
Visit the link in the
that acts as a
pop-up and follow
wizard, detects
the steps in the
what platform
web page to
you are using,
download and
and delivers the
install DigiCert
latest release of
Desktop Client.
the DigiCert
Desktop Client
installer
software.
After the
installation, you
might get a prompt
to enable DigiCert
Desktop Client for
desired browsers.
Click on Enable for
the browsers you
wish to use via
DigiCert Desktop
Client.
Retry the
enrollment.
Click OK on the
prompt.
Manual Approval enrollment flow
Steps Details Notes
Navigate to the SSP
URL and login using
your IdP credentials
Click on Enroll under
Actions column
against the Profile
Name configured.
pg. 21DigiCert® PKI Platform -UAA Production Details
Complete the required
Depending on the enrollment.
enrollment method
and issuance
method, user might
be presented with a
pop-up window to
enter the certificate
fields, a window to
enter the password
to encrypt the
PKCS12 file, or a
window to enter a
CSR.
On completing the
enrollment flow,
status of the
enrollment will be
set to “Pending” until
it is manually
approved by an
Administrator in PKI
Manager portal.
On Approval, user
will receive an
approval email with
certificate p7b.
For Browser Admin can update
PKCS12 enrollment certificate approval
method, user must email template from
visit the SSP portal PKI Manager-> Mange
to download the Certificate Profile
certificate: page
• Click on
Download
• Enter PKCS12
password. Edit the email
template to include
link to UAA SSP Portal
pg. 22DigiCert® PKI Platform -UAA Production Details
URL which users can
use to install their
certificates.
For DDC enrollment Depending on the
method, user must platform being used
visit the SSP portal to install the
to install the certificate, a different
certificate: success pop-up
message will be
Click on Install. displayed.
Approval email
content sent to the
For CSR enrollment user will also contain
method, user can the certificate in
visit the SSP portal PKCS7 format.
to download the
approved certificate:
Click on Download,
to download the
certificate in PKCS7
format.
pg. 23DigiCert® PKI Platform -UAA Production Details
How to manage your certificate
The Self-Service Portal allows users to perform the below operations:
• Download certificate
• Revoke certificate
• Renew certificate
Certificate Operation Steps Screenshots
Download Click on Download to download
the certificate in PKCS12
format.
In Download certificate from
Self-Service Portal mode, a
pop-up to enter the password
of the key will appear. Enter
your password and click OK to
download the certificate.
Revoke Click on Revoke and OK on the
Confirmation pop-up window to
revoke the certificate from the
DigiCert PKI Platform service.
Click on Renew and Submit on
Renew the next page to renew the
certificate
pg. 24DigiCert® PKI Platform -UAA Production Details Additional information After logging in to the UAA Admin portal, a Getting Started wizard walks you through a step-by-step process to configure SAML based enrollments: Clicking the icon on the top-right side of the UAA Self-Service Portal optimizes the display for smaller devices, such as smartphones: pg. 25
DigiCert® PKI Platform -UAA Production Details
Known Issues
• [UAA User] Cannot use % or \ in certificate attribute values when enrolling for a
certificate.
Troubleshooting
Even after installing DDC, while picking up the certificate it might not be detected and
you might get following error pop up.
Restart the DDC and retry the enrollment.
pg. 26You can also read
