Workflow Using an X.509 Certificate

This topic describes the workflow for using an X.509 Certificate with the gateway.
gateway83
This topic describes the workflow for using an X.509 Certificate with the
CA API Gateway
.
The "Trusted Authority" is the certificate authority (CA) that issues and manages security credentials and which is responsible for authentication. The "Federated Gateway" is the web service provider that is responsible for authorization.
The table below summarizes how to configure identity bridging using an X.509 Certificate credential source. Follow the cross references for more details of each step.
Step
For more information, see...
Step 1
: Confirm that your system meets the requirements for configuring identity bridging with SAML.
Step
2
: Import one or more Trusted Gateway A certificates into the Federated Gateway B trust store.
See
Certificate Usage Scenarios
below for the correct procedure based on the type of certificate.
Step 3
: Create a new Federated Identity Provider.
  • In Step 1 of the Create Federated Identity Provider Wizard, select [
    X.509 Certificate
    ] for Credential Source Type Allowed.
  • For the "CA Certificate ONLY" and "Both CA Certificate and Client Certificates" scenarios, click [
    Add
    ] in Step 2 of the Wizard to attach the imported Trusted Gateway A CA certificate.
    Do not click [
    Add
    ] if your scenario is "Individual Client Certificate ONLY".
Step 4
: If using the "CA Certificate ONLY" and "Both CA Certificate and Client Certificates" scenarios, create a new federated user for each client certificate that you want to trust, then import the client certificate.
  • In the Create Federated User dialog, X509 Subject DN field: Enter the subject DN that corresponds to the Issued to: value in the client certificate (see Edit a Certificate):
Workflow_X509_image.png
  • Select the Define Additional Properties option and then import the target client certificate (see step 3 under Create a Federated User.
Step 5
: Add additional federated users, federated groups, and/or virtual groups as required.
  • You cannot create a virtual group for a federated identity provider (FIP) unless it contains at least one trusted certificate. In this workflow, this is a CA certificate that is attached to the FIP using the Federated Identity Provider Wizard.
  • A virtual group cannot be created in the "Client Certificate ONLY" scenario, because a trusted certificate does not exist in the FIP.
Step 6
: In the CA API Gateway - XML VPN Client, configure Gateway Accounts use either the Full Identity Bridging or Ad-Hoc Identity Bridging methods.
See "Configure Gateway Accounts" for more information on which method to choose.
See "Full Identity Bridging Method" or "Ad-Hoc Identity Bridging" for details of each method.
Step 7
: Consume the shared web service.
 
Certificate Usage Scenarios
The following table summarizes how to import Trusted Authority certificates into the Federated Gateway trust store based on the certificate involved.
The certificate importation occurs in Step 3 of the workflow. Be sure to resume the workflow at Step 4 when done.
Scenario 1: CA Certificates ONLY
When only CA (Certificate Authority) certificates are involved, import them into the Federated Gateway B trust store using the Add Certificate Wizard. In Step 3 of the wizard, be sure to select the Signing Client Certificates option. This signifies that the CA certificate is trusted to authenticate identities in this FIP by signing their X.509 certificates.
Scenario 2: Individual Client Certificates ONLY
When only client certificate are involved, import them via the Additional Properties dialog of a Federated Identity Provider User (step 3 of Creating a Federated User). You can do this when performing Step 6 of the workflow. Do not attach imported client certificates to the FIP in the Create Federated Identity Provider Wizard.
Additional notes about this scenario:
  • The Federated Identity Provider (FIP) must not contain any trusted certificates (either CA or server). To confirm this, the Trusted Certificates box in Step 2 of the Create Federated Identity Provider Wizard must be empty when you are performing workflow Step 4.
    If trusted certificates are added to the FIP, the
    API Gateway
    will assume you are using "Scenario 3: CA Certificate and Individual Client Certificates" instead.
  • Since no trusted certificates are attached to the FIP, you cannot create a virtual group for the FIP.
  • When no CA certificates are trusted by the FIP, federated users must have client certificates in order to be authorized.
  • When a client certificate is imported for a federated user, incoming certificate-based credentials will be compared against the stored client certificate. Any mismatch will cause an authorization failure, even if the certificate in the request was signed by a trusted CA.
Scenario 3: Both CA Certificate and Individual Client Certificates
When both CA and client certificates are involved, do the following:
  • Import the CA certificate as described in Adding a New Certificate. When you reach Step 3 of the Add Certificate Wizard, select the Signing Client Certificates option. This signifies that the CA certificate is trusted to sign the client certificates for federated users in this FIP.
  • Import the client certificates as described in Step 5 of the workflow. Do not attach imported client certificates to the FIP in the Create Federated Identity Provider Wizard.
Additional notes about this scenario:
  • The individual client certificates must be signed by the CA certificate.
  • When a client certificate is imported for a federated user, incoming certificate-based credentials will be compared against the stored client certificate. Any mismatch will cause an authorization failure, even if the certificate in the request was signed by a trusted CA.