Access Keys:
Skip to content (Access Key - 0)

Dorian

Configuring Dorian

[ Dorian: Administrators Guide | Developers Guide | Users Guide | caGrid: Documentation Guides ]

Dorian is configured through a single configuration file which is located at DORIAN_LOCATION/etc/dorian-conf.xml. Dorian uses a Mysql Database as its backend data store; you must provide Dorian with the connection details for your Mysql database. The DatabaseConfiguration element in the Dorian configuration file is used to specify the connection information for your Mysql database. You will need to specify the host of your database server, the port that the server runs on, and the username and password of a database user.

    <DatabaseConfiguration>
    <host>localhost</host>
    <port>3306</port>
    <username>root</username>
    <password></password>
    </DatabaseConfiguration>

When Dorian is first initialized it will create a database named with the value of the DorianInternalId element. Dorian will also proceed to setup its database schema in the database it created. In order to do so Dorian needs to be configured with a database user that has the appropriate permissions. If you do not wish to provide Dorian with such a user you may create the database manually and provide Dorian with a user whom has the permission to modify the database schema. In this scenario Dorian will not create the database but will proceed to setup its database schema in the database that was manually created.

<DorianInternalId>DORIAN</DorianInternalId>


Dorian Identity Provider Configuration

The Dorian Identity Provider is configured in the IdentityProviderConfiguration element, shown below. The UIDLength element allows the minimum and maximum user id length to be specified. The PasswordLength element allows the minimum and maximum password length to be specified. The RegistrationPolicy element specifies the registration policy to use. The registration policy tells the Dorian IdP what to do when a new user registers. The Dorian IdP supports two types of registration policies; manual and automatic. A manual registration policy requires administrators to approve new accounts; an automatic registration process automatically approves new accounts. To specify a manual registration policy set the class attribute of the registration-policy element equal to gov.nih.nci.cagrid.dorian.service.idp.ManualRegistrationPolicy. To specify an automatic registration policy set the class attribute of the registration-policy element equal to gov.nih.nci.cagrid.dorian.service.idp.AutomaticRegistrationPolicy. The AssertingCredentials element specifies the configuration for the Dorian IdP's signing credentials or the credentials Dorian uses in signing SAML Assertions. Currently the DorianIdP automatically generates a set of signing credentials which are signed by the Dorian certificate authority. In the future the Dorian IdP may allow the signing credentials to be imported. The AutoRenew elements specifies whether or not the Dorian IdP should renew the signing credentials once they expire. The KeyPassword element specifies the password used to encrypt the private key that is used for signing SAML assertions.

        <IdentityProviderConfiguration>
            <IdentityProviderName>Dorian IdP</IdentityProviderName>
             <UIDLength min="4" max="15"/>
            <PasswordLength min="10" max="20"/>
            <PasswordSecurityPolicy>
            	<LockoutTime hours="4" minutes="0" seconds="0"/>
            	<MaxConsecutiveInvalidLogins>5</MaxConsecutiveInvalidLogins>
            	<MaxTotalInvalidLogins>500</MaxTotalInvalidLogins>
            </PasswordSecurityPolicy>
            <RegistrationPolicy>gov.nih.nci.cagrid.dorian.service.idp.ManualRegistrationPolicy</RegistrationPolicy>
            <AssertingCredentials>
                <AutoRenew>true</AutoRenew>
                <KeyPassword>idpkey</KeyPassword>
            </AssertingCredentials>
        </IdentityProviderConfiguration>


Dorian Identity Management Configuration

The Identity Management aspects of Dorian are configured in the IdentityFederationConfiguration element (shown below). The IdentityProviderNameLength element allows the specification of a minimum and maximum IdP name length.

When a user is granted an account Dorian assigns them a unique identity such that the user can be uniquely identified in the Grid. This identity will be composed of 1) Prefix of the CA Subject, 2) The Identity Provider that asserts their identity, and 3) their local identity within their Identity Provider. For representing a user's Identity Provider, Dorian can use the human readable name of the IdP or the unique id assigned by Dorian for the IdP. The IdentityAssignmentPolicy element specifies which approach to use. To use the human readable name approach the value of the IdentityAssignmentPolicy element should be specified as "name". To use the unique id assigned by Dorian to represent the user's IdP in their identity the value of the IdentityAssignmentPolicy element should be specified as "id".

The CredentialLifetime element specifies how long a user's long term grid credentials are valid for from the time they are created. The lifetime of the grid credentials is limited by the lifetime of the certificate authority, in cases where the lifetime of the grid credentials exceeds the lifetime of the CA, the grid credentials will be issued with the same life time as the CA.

The HostCertificateAutoApproval element specifies to Dorian whether or not to automatically approve host certificate requests submitted to Dorian. When automatic approval is enabled (HostCertificateAutoApproval value set to true) a host certificate will immediately be created and signed when a host certificate request is received. When automatic approval is disabled (HostCertificateAutoApproval value set to false) host certificate requests will require approval of a Dorian administrator.

The ProxyLifetime element specifies the maximum amount of time that a user may request a proxy certificate to be created for.

The AccountPolicies element specifies a list of user policies that are supported by the Dorian. These policies designate how Dorian should handle users from a specified Identity Provider. Policies generally dictate what to do when a new user is encountered and what to do when a user's long term certificate expires. Currently Dorian supports four policies:

1. Auto Approval / Auto Renewal - A new user is automatically registered and given access to the grid. (user's status is active) When a user's whose long term certificate expires it is automatically renewed.
2. Auto Approval / Manual Renewal - A new user is automatically registered and given access to the grid. (user's status is active) When a user's whose long term certificate expires, an administrator is required to manually renew it.
3. Manual Approval / Auto Renewal - A new user is automatically registered but not granted access, and administrator is required to grant access. (user's status is pending) When a user's whose long term certificate expires it is automatically renewed.
4. Manual Approval / Manual Renewal - A new user is automatically registered but not granted access, and administrator is required to grant access. (user's status is pending) When a user's whose long term certificate expires, an administrator is required to manually renew it.

Besides the four policies released with Dorian, you may also create your own by providing an implementation of the gov.nih.nci.cagrid.dorian.service.ifs.UserPolicy class.

The CRLPublish element(optional) specifies the GTS(s) in which Dorian should publish its certificate authority CRLS. In order for Dorian to publish CRLS to a GTS, the Dorian Certificate Authority must be registered in the GTS as a trusted authority. Dorian must also be granted permission within the GTS to publish a CRL for its certificate authority.

    <IdentityFederationConfiguration>
            <IdentityProviderNameLength min="3" max="50"/>
            <IdentityAssignmentPolicy>name</IdentityAssignmentPolicy>
            <CredentialPolicy>
                <CredentialLifetime years="1" months="0" days="0" hours="0" minutes="0" seconds="0"/>
                <HostCertificateAutoApproval>false</HostCertificateAutoApproval>
            </CredentialPolicy>
            <ProxyPolicy>
                <ProxyLifetime hours="12" minutes="0" seconds="0"/>
            </ProxyPolicy>
            <AccountPolicies>
                <AccountPolicy>
                    <name>Manual Approval / Manual Renewal</name>
                    <classname>gov.nih.nci.cagrid.dorian.service.ifs.ManualApprovalPolicy</classname>
                </AccountPolicy>
                <AccountPolicy>
                    <name>Manual Approval / Auto Renewal</name>
                    <classname>gov.nih.nci.cagrid.dorian.service.ifs.ManualApprovalAutoRenewalPolicy</classname>
                </AccountPolicy>
                <AccountPolicy>
                    <name>Auto Approval / Manual Renewal</name>
                    <classname>gov.nih.nci.cagrid.dorian.service.ifs.AutoApprovalPolicy</classname>
                </AccountPolicy>
                <AccountPolicy>
                    <name>Auto Approval / Auto Renewal</name>
                    <classname>gov.nih.nci.cagrid.dorian.service.ifs.AutoApprovalAutoRenewalPolicy</classname>
                </AccountPolicy>
            </AccountPolicies>
            <CRLPublish>
                <gts>https://cagrid01.bmi.ohio-state.edu:8442/wsrf/services/cagrid/GTS</gts>
            </CRLPublish>
    </IdentityFederationConfiguration>


Dorian Certificate Authority Configuration

Dorian maintains its own certificate authority, which it uses to issue and revoke grid credentials. Depending on your deployment requirements, Dorian can either be configured to use an existing certificate authority or it can generate a new certificate authority. The DorianCAConfiguration element in the Dorian configuration specifies the configuration details for Dorian's certificate authority. The Dorian certificate authority supports the following approaches for creating and storing certificates and private keys:

  • DBCA - User and CA private keys are created in memory and stored along with their corresponding certificates in Dorian's MySQL database.
  • Eracom - User and CA private keys are generated and stored in a SafeNet Protect Server Gold Hardware Security Module (HSM)
  • EracomHybrid - The CA private key is generated and stored in a SafeNet Protect Server Gold HSM. User private keys are generated in memory and wrapped by a 256 bit RSA key stored and maintained in a SafeNet Protect Server Gold HSM. The wrapped user private keys are stored in a database.

By default Dorian is configured to use the DBCA approach. The default approach can be changed by setting the value of the CertificateAuthorityType to the desired approach (DBCA or Eracom or EracomHybrid).

Eracom and EracomHybrid approaches REQUIRE that the Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy Files (Java 5, Java 6) be installed into your JVM.

The existence of the AutoCreate element specifies to Dorian that is should create a new certificate authority. If you have configured Dorian to create a new certificate authority, you must specify the subject of the certificate authority (CASubject element), the key size (512, 1024, or 2048) of the CA's private key (CAKeySize element), and the lifetime that the CA will be valid for (lifetime element).

    <DorianCAConfiguration>
        <CertificateAuthorityType>DBCA</CertificateAuthorityType>
        <CertificateAuthorityPassword>admin</CertificateAuthorityPassword>
        <CertificatePolicyOID>5.5.5.5.5.5.5555.555.5.5</CertificatePolicyOID>
        <UserKeySize>1024</UserKeySize>
        <AutoCreate>
            <CASubject>C=US,O=abc,OU=xyz,OU=caGrid,OU=Users,CN=caGrid Dorian CA</CASubject>
            <CAKeySize>2048</CAKeySize>
            <lifetime years="10" months="0" days="0" hours="0" minutes="0" seconds="0"/>
        </AutoCreate>
        <AutoRenewal years="10" months="0" days="0" hours="0" minutes="0" seconds="0"/>
    </DorianCAConfiguration>

Below is an example of a configuration that specifies the use of an existing certificate authority. If you have configured Dorian to user an existing certificate authority you must import it before running Dorian for the first time. This can be done from the Dorian installation directory by typing ant importCA. Doing so will run a command line program that will prompt you for the location of the certificate and private key of the certificate authority. It should be noted that the import tool requires both the certificate and private key to be in PEM format. You will be also asked to provide a password, if it is needed to decrypt the private key.

    <DorianCAConfiguration>
        <CertificateAuthorityType>DBCA</CertificateAuthorityType>
        <CertificateAuthorityPassword>admin</CertificateAuthorityPassword>
        <CertificatePolicyOID>5.5.5.5.5.5.5555.555.5.5</CertificatePolicyOID>
        <UserKeySize>1024</UserKeySize>
        <AutoRenewal years="10" months="0" days="0" hours="0" minutes="0" seconds="0"/>
    </DorianCAConfiguration>

Despite whether your configuration specifies to create a new certificate authority or use an existing one, you must specify a password that Dorian should use for accessing the CA private key; this is done in the CertificateAuthorityPassword element. It should be noted that the CertificateAuthorityPassword element should be configured before importing a certificate authority, since the import tool will used the ca password specified when encrypting the CA private key. The CertificatePolicyOID is an optional element that specifies the OID of the CA's policy. The UserKeySize element specifies the key size (512, 1024, or 2048) that Dorian should use in creating user credentials. The AutoRenewal element instructs Dorian what to do when a certificate authority expires. If the AutoRenewal element is specified Dorian will renew the certificate authority when it expires for the lifetime specified. If the AutoRenewal element is not specified, Dorian will allow the certificate authority to expire, invalidating any grid user accounts that it manages.
Last edited by
Knowledge Center (1157 days ago) , ...
Adaptavist Theme Builder Powered by Atlassian Confluence