wiki:IdpKeyRollOver
Last modified 8 years ago Last modified on 12/15/11 14:06:39

Shibboleth / IdP Key Roll Over

This page documents the process of rolling over the IdP's keys. This includes the process of generating a new certificate for the IdP. The certificate and key are only used for signing the assertions and securing the attribute query back channel that is not user facing.

The process from the 10k foot level is to add a second key and cert to the IdP and its metadata for distribution ahead of the actual roll over. Once all of the SPs have the new metadata then the IdP can be rolled over to using the new key and cert and the SPs will transparently follow since they have both the new cert and old cert in metadata.

Note: All operations in this procedure occur under the tomcat user.

  1. Generate a new key/certificate:
    -bash-3.2$ openssl req -x509 -newkey rsa:2048 -nodes -days 1095 -keyout idp.new.key -out idp.new.crt
    Generating a 2048 bit RSA private key
    ...........................................+++
    ............................................................+++
    writing new private key to 'idp.new.key'
    -----
    You are about to be asked to enter information that will be incorporated
    into your certificate request.
    What you are about to enter is what is called a Distinguished Name or a DN.
    There are quite a few fields but you can leave some blank
    For some fields there will be a default value,
    If you enter '.', the field will be left blank.
    -----
    Country Name (2 letter code) [GB]:US
    State or Province Name (full name) [Berkshire]:Alaska
    Locality Name (eg, city) [Newbury]:Fairbanks
    Organization Name (eg, company) [My Company Ltd]:University of Alaska
    Organizational Unit Name (eg, section) []:Office of Information Technology
    Common Name (eg, your name or your server's hostname) []:idp.alaska.edu
    Email Address []:iam@alaska.edu
    
  1. Copy the key/certificate into the credentials directory of the IdP installation. You will need to do this on all Shibboleth servers as the credential directory is not managed in subversion. See [ IAM Project Hosts ].
    -bash-3.2$ cp idp.new.crt /opt/shibboleth-idp/credentials/
    -bash-3.2$ cp idp.new.key /opt/shibboleth-idp/credentials/
    
  1. Add the new key/certificate to the relying party configuration. After this step there should be two "security:Credential" stanzas. One with the "IdPCredential" id and one with the "IdPCredentialNew" id.
    -bash-3.2$ svn co svn+ssh://sxjpm@iron.alaska.edu/usr/local/iam/shib-svn/idp/trunk/conf
    -bash-3.2$ vi conf/relying-party.xml
    ...
        <security:Credential id="IdPCredentialNew" xsi:type="security:X509Filesystem">
            <security:PrivateKey>/opt/shibboleth-idp/credentials/idp.new.key</security:PrivateKey>
            <security:Certificate>/opt/shibboleth-idp/credentials/idp.new.crt</security:Certificate>
        </security:Credential>
    ...
    :wq!
    -bash-3.2$ svn ci conf/relying-party.xml -m "Added new IdP key/cert."
    
  1. Add the new certificate to the IdP metadata. There should be two "<KeyDescriptor>" stanzas after this step in the metadata for the "<IDPSSODescriptor>" stanza and the "<AttributeAuthorityDescriptor>" stanza.
    -bash-3.2$ cat idp.new.crt 
    -----BEGIN CERTIFICATE-----
    MIIFDDCCA/SgAwIBAgIJAN58IPd0DVLpMA0GCSqGSIb3DQEBBQUAMIG0MQswCQYD
    VQQGEwJVUzEPMA0GA1UECBMGQWxhc2thMRIwEAYDVQQHEwlGYWlyYmFua3MxHTAb
    BgNVBAoTFFVuaXZlcnNpdHkgb2YgQWxhc2thMSkwJwYDVQQLEyBPZmZpY2Ugb2Yg
    SW5mb3JtYXRpb24gVGVjaG5vbG9neTEXMBUGA1UEAxMOaWRwLmFsYXNrYS5lZHUx
    HTAbBgkqhkiG9w0BCQEWDmlhbUBhbGFza2EuZWR1MB4XDTExMDcwNzIzMDc1NFoX
    DTE0MDcwNjIzMDc1NFowgbQxCzAJBgNVBAYTAlVTMQ8wDQYDVQQIEwZBbGFza2Ex
    EjAQBgNVBAcTCUZhaXJiYW5rczEdMBsGA1UEChMUVW5pdmVyc2l0eSBvZiBBbGFz
    a2ExKTAnBgNVBAsTIE9mZmljZSBvZiBJbmZvcm1hdGlvbiBUZWNobm9sb2d5MRcw
    FQYDVQQDEw5pZHAuYWxhc2thLmVkdTEdMBsGCSqGSIb3DQEJARYOaWFtQGFsYXNr
    YS5lZHUwggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQCqzXokjJWPQdz8
    cHsoSiNADLwYX89wxjTe5Xp47iqSWlx3eaxQlOOSY9OJ59dE4+tN8ACqiWJp0iga
    /GpyEH93jLoZBToTGMImto0SgC1I2eTk+htpJ6wn7Mu8fKpBhZ74OYiXf6NHoMCJ
    w4exXAv+inZcbcIrLnfUKPQxbRhoKvJO/DQHvMl7KNtN+H0rjFNu0ASTdQ96hffi
    SQpolP9kb1cnGH1xGmAcm+4O3LG+3//qNk22R0JpP+UAu3ZVITMXzbhOzyZ26RQK
    DA16v2kDzJEONJJM9/rk/YlG35cLea72NjTs4IPoyJLSk6ZaFZV4z4wsC5ChGoKB
    4r3hCOqRAgMBAAGjggEdMIIBGTAdBgNVHQ4EFgQU2V5wFIfP1b31LPo89aUrJX2i
    MZkwgekGA1UdIwSB4TCB3oAU2V5wFIfP1b31LPo89aUrJX2iMZmhgbqkgbcwgbQx
    CzAJBgNVBAYTAlVTMQ8wDQYDVQQIEwZBbGFza2ExEjAQBgNVBAcTCUZhaXJiYW5r
    czEdMBsGA1UEChMUVW5pdmVyc2l0eSBvZiBBbGFza2ExKTAnBgNVBAsTIE9mZmlj
    ZSBvZiBJbmZvcm1hdGlvbiBUZWNobm9sb2d5MRcwFQYDVQQDEw5pZHAuYWxhc2th
    LmVkdTEdMBsGCSqGSIb3DQEJARYOaWFtQGFsYXNrYS5lZHWCCQDefCD3dA1S6TAM
    BgNVHRMEBTADAQH/MA0GCSqGSIb3DQEBBQUAA4IBAQBiXjlb84MPNRuPISvPa/hG
    qbZWDAYRvH3b+/3JxGeDtkcBYkmk8/HZZKRxxbdm9OBSYmkdhY/NqA+LVd08nP6T
    rpWM1sYIGfXo3OoyQOgDiwB1RnJwTRsHX+qUkKZWeUF5TzW7dhNtW5Efv7kMMU+X
    dBy3y0HhLJKUnUEgRD6c21bAaRow1uowhNZMZ9Pl+TbJyiOZdWPPUFSXDk/VarwI
    DOq2Qf8ih5EnbMLVtIDRlAUkfoskx69nWiwt4pmw5BjwnthYdNCfmZLoEJbpWCh8
    8QBWVqNSK1+XRDa6lm1v3UkNMBR3+TZG3MAVcYrwHDnUTayxGZ6psy2yY+ET0mwH
    -----END CERTIFICATE-----
    -bash-3.2$ svn co svn+ssh://sxjpm@iron.alaska.edu/usr/local/iam/shib-svn/idp/trunk/metadata
    -bash-3.2$ vi metadata/idp-metadata.xml
    ...
        <IDPSSODescriptor protocolSupportEnumeration="urn:mace:shibboleth:1.0 urn:oasis:names:tc:SAML:1.1:protocol urn:oasis:names:tc:SAML:2.0:protocol">
    ...
            <KeyDescriptor use="signing">
                <ds:KeyInfo>
                    <ds:X509Data>
                        <ds:X509Certificate>
    MIIFDDCCA/SgAwIBAgIJAN58IPd0DVLpMA0GCSqGSIb3DQEBBQUAMIG0MQswCQYD
    VQQGEwJVUzEPMA0GA1UECBMGQWxhc2thMRIwEAYDVQQHEwlGYWlyYmFua3MxHTAb
    BgNVBAoTFFVuaXZlcnNpdHkgb2YgQWxhc2thMSkwJwYDVQQLEyBPZmZpY2Ugb2Yg
    SW5mb3JtYXRpb24gVGVjaG5vbG9neTEXMBUGA1UEAxMOaWRwLmFsYXNrYS5lZHUx
    HTAbBgkqhkiG9w0BCQEWDmlhbUBhbGFza2EuZWR1MB4XDTExMDcwNzIzMDc1NFoX
    DTE0MDcwNjIzMDc1NFowgbQxCzAJBgNVBAYTAlVTMQ8wDQYDVQQIEwZBbGFza2Ex
    EjAQBgNVBAcTCUZhaXJiYW5rczEdMBsGA1UEChMUVW5pdmVyc2l0eSBvZiBBbGFz
    a2ExKTAnBgNVBAsTIE9mZmljZSBvZiBJbmZvcm1hdGlvbiBUZWNobm9sb2d5MRcw
    FQYDVQQDEw5pZHAuYWxhc2thLmVkdTEdMBsGCSqGSIb3DQEJARYOaWFtQGFsYXNr
    YS5lZHUwggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQCqzXokjJWPQdz8
    cHsoSiNADLwYX89wxjTe5Xp47iqSWlx3eaxQlOOSY9OJ59dE4+tN8ACqiWJp0iga
    /GpyEH93jLoZBToTGMImto0SgC1I2eTk+htpJ6wn7Mu8fKpBhZ74OYiXf6NHoMCJ
    w4exXAv+inZcbcIrLnfUKPQxbRhoKvJO/DQHvMl7KNtN+H0rjFNu0ASTdQ96hffi
    SQpolP9kb1cnGH1xGmAcm+4O3LG+3//qNk22R0JpP+UAu3ZVITMXzbhOzyZ26RQK
    DA16v2kDzJEONJJM9/rk/YlG35cLea72NjTs4IPoyJLSk6ZaFZV4z4wsC5ChGoKB
    4r3hCOqRAgMBAAGjggEdMIIBGTAdBgNVHQ4EFgQU2V5wFIfP1b31LPo89aUrJX2i
    MZkwgekGA1UdIwSB4TCB3oAU2V5wFIfP1b31LPo89aUrJX2iMZmhgbqkgbcwgbQx
    CzAJBgNVBAYTAlVTMQ8wDQYDVQQIEwZBbGFza2ExEjAQBgNVBAcTCUZhaXJiYW5r
    czEdMBsGA1UEChMUVW5pdmVyc2l0eSBvZiBBbGFza2ExKTAnBgNVBAsTIE9mZmlj
    ZSBvZiBJbmZvcm1hdGlvbiBUZWNobm9sb2d5MRcwFQYDVQQDEw5pZHAuYWxhc2th
    LmVkdTEdMBsGCSqGSIb3DQEJARYOaWFtQGFsYXNrYS5lZHWCCQDefCD3dA1S6TAM
    BgNVHRMEBTADAQH/MA0GCSqGSIb3DQEBBQUAA4IBAQBiXjlb84MPNRuPISvPa/hG
    qbZWDAYRvH3b+/3JxGeDtkcBYkmk8/HZZKRxxbdm9OBSYmkdhY/NqA+LVd08nP6T
    rpWM1sYIGfXo3OoyQOgDiwB1RnJwTRsHX+qUkKZWeUF5TzW7dhNtW5Efv7kMMU+X
    dBy3y0HhLJKUnUEgRD6c21bAaRow1uowhNZMZ9Pl+TbJyiOZdWPPUFSXDk/VarwI
    DOq2Qf8ih5EnbMLVtIDRlAUkfoskx69nWiwt4pmw5BjwnthYdNCfmZLoEJbpWCh8
    8QBWVqNSK1+XRDa6lm1v3UkNMBR3+TZG3MAVcYrwHDnUTayxGZ6psy2yY+ET0mwH
                        </ds:X509Certificate>
                    </ds:X509Data>
                </ds:KeyInfo>
            </KeyDescriptor>
    ...
        </IDPSSODescriptor>
    
        <AttributeAuthorityDescriptor protocolSupportEnumeration="urn:oasis:names:tc:SAML:1.1:protocol urn:oasis:names:tc:SAML:2.0:protocol">
    ...
            <KeyDescriptor use="signing">
                <ds:KeyInfo>
                    <ds:X509Data>
                        <ds:X509Certificate>
    MIIFDDCCA/SgAwIBAgIJAN58IPd0DVLpMA0GCSqGSIb3DQEBBQUAMIG0MQswCQYD
    VQQGEwJVUzEPMA0GA1UECBMGQWxhc2thMRIwEAYDVQQHEwlGYWlyYmFua3MxHTAb
    BgNVBAoTFFVuaXZlcnNpdHkgb2YgQWxhc2thMSkwJwYDVQQLEyBPZmZpY2Ugb2Yg
    SW5mb3JtYXRpb24gVGVjaG5vbG9neTEXMBUGA1UEAxMOaWRwLmFsYXNrYS5lZHUx
    HTAbBgkqhkiG9w0BCQEWDmlhbUBhbGFza2EuZWR1MB4XDTExMDcwNzIzMDc1NFoX
    DTE0MDcwNjIzMDc1NFowgbQxCzAJBgNVBAYTAlVTMQ8wDQYDVQQIEwZBbGFza2Ex
    EjAQBgNVBAcTCUZhaXJiYW5rczEdMBsGA1UEChMUVW5pdmVyc2l0eSBvZiBBbGFz
    a2ExKTAnBgNVBAsTIE9mZmljZSBvZiBJbmZvcm1hdGlvbiBUZWNobm9sb2d5MRcw
    FQYDVQQDEw5pZHAuYWxhc2thLmVkdTEdMBsGCSqGSIb3DQEJARYOaWFtQGFsYXNr
    YS5lZHUwggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQCqzXokjJWPQdz8
    cHsoSiNADLwYX89wxjTe5Xp47iqSWlx3eaxQlOOSY9OJ59dE4+tN8ACqiWJp0iga
    /GpyEH93jLoZBToTGMImto0SgC1I2eTk+htpJ6wn7Mu8fKpBhZ74OYiXf6NHoMCJ
    w4exXAv+inZcbcIrLnfUKPQxbRhoKvJO/DQHvMl7KNtN+H0rjFNu0ASTdQ96hffi
    SQpolP9kb1cnGH1xGmAcm+4O3LG+3//qNk22R0JpP+UAu3ZVITMXzbhOzyZ26RQK
    DA16v2kDzJEONJJM9/rk/YlG35cLea72NjTs4IPoyJLSk6ZaFZV4z4wsC5ChGoKB
    4r3hCOqRAgMBAAGjggEdMIIBGTAdBgNVHQ4EFgQU2V5wFIfP1b31LPo89aUrJX2i
    MZkwgekGA1UdIwSB4TCB3oAU2V5wFIfP1b31LPo89aUrJX2iMZmhgbqkgbcwgbQx
    CzAJBgNVBAYTAlVTMQ8wDQYDVQQIEwZBbGFza2ExEjAQBgNVBAcTCUZhaXJiYW5r
    czEdMBsGA1UEChMUVW5pdmVyc2l0eSBvZiBBbGFza2ExKTAnBgNVBAsTIE9mZmlj
    ZSBvZiBJbmZvcm1hdGlvbiBUZWNobm9sb2d5MRcwFQYDVQQDEw5pZHAuYWxhc2th
    LmVkdTEdMBsGCSqGSIb3DQEJARYOaWFtQGFsYXNrYS5lZHWCCQDefCD3dA1S6TAM
    BgNVHRMEBTADAQH/MA0GCSqGSIb3DQEBBQUAA4IBAQBiXjlb84MPNRuPISvPa/hG
    qbZWDAYRvH3b+/3JxGeDtkcBYkmk8/HZZKRxxbdm9OBSYmkdhY/NqA+LVd08nP6T
    rpWM1sYIGfXo3OoyQOgDiwB1RnJwTRsHX+qUkKZWeUF5TzW7dhNtW5Efv7kMMU+X
    dBy3y0HhLJKUnUEgRD6c21bAaRow1uowhNZMZ9Pl+TbJyiOZdWPPUFSXDk/VarwI
    DOq2Qf8ih5EnbMLVtIDRlAUkfoskx69nWiwt4pmw5BjwnthYdNCfmZLoEJbpWCh8
    8QBWVqNSK1+XRDa6lm1v3UkNMBR3+TZG3MAVcYrwHDnUTayxGZ6psy2yY+ET0mwH
                        </ds:X509Certificate>
                    </ds:X509Data>
                </ds:KeyInfo>
            </KeyDescriptor>
    ...
    :wq!
    -bash-3.2$ svn ci metadata/idp-metadata.xml -m "Added new IdP cert."
    
  1. Submit the new certificate to InCommon for inclusion in the next federation metadata publication. This occurs daily and is done from an administrative web interface. See David Bantz for more details as he currently is the only individual with access to this.
  1. Test config changes according to procedure. See [ Test IdP Config Change ].
  1. Notify non-federation SPs of metadata change and instruct them to update. SPs in the InCommon federation should be polling the InCommon metadata distribution point daily. Wait for SPs to get metadata. See [ InCommon Metadata ].
  1. Move to the new key/certificate and delete the old key/certificate "security:Credential" stanza in the relying party configuration. After this step there should be only one "security:Credential" stanza that points to the key/cert. Note: The id must be "IdPCredential".
    -bash-3.2$ svn co svn+ssh://sxjpm@iron.alaska.edu/usr/local/iam/shib-svn/idp/trunk/conf
    -bash-3.2$ vi conf/relying-party.xml
    ...
        <security:Credential id="IdPCredential" xsi:type="security:X509Filesystem">
            <security:PrivateKey>/opt/shibboleth-idp/credentials/idp.new.key</security:PrivateKey>
            <security:Certificate>/opt/shibboleth-idp/credentials/idp.new.crt</security:Certificate>
        </security:Credential>
    ...
    :wq!
    -bash-3.2$ svn ci conf/relying-party.xml -m "Moved to new IdP key/cert and deleted old IdP key/cert."
    
  1. Move to the new key/certificate in the IdP metadata. There should be one "<KeyDescriptor>" stanza after this step in the metadata for the new cert in the "<IDPSSODescriptor>" stanza and the "<AttributeAuthorityDescriptor>" stanza.
    -bash-3.2$ svn co svn+ssh://sxjpm@iron.alaska.edu/usr/local/iam/shib-svn/idp/trunk/metadata
    -bash-3.2$ vi metadata/idp-metadata.xml
    ...
    :wq!
    -bash-3.2$ svn ci metadata/idp-metadata.xml -m "Moved to new IdP cert and deleted old cert."
    
  1. Create a new Java Key Store for Tomcat containing the new key/cert for securing the back channel. You will need the ImportKey Java utility for importing a pre-existing cert/key into a Java Key Store. You will also need the InCommon intermediary cert, and the AddTrust Root CA cert for this process. See [ Import Key Util ], [ InCommon Cert ], and [ AddTrust Cert ].
    -bash-3.2$ openssl pkcs8 -topk8 -nocrypt -in idp.new.key -out idp.new.key.der -outform der
    -bash-3.2$ openssl x509 -in idp.new.crt -out idp.new.crt.der -outform der
    -bash-3.2$ openssl x509 -in incommon.crt -out incommon.crt.der -outform der
    -bash-3.2$ openssl x509 -in addtrust.crt -out addtrust.crt.der -outform der
    -bash-3.2$ cat incommon.crt.der addtrust.crt.der >> idp.new.crt.der
    -bash-3.2$ java ImportKey idp.new.key.der idp.new.crt.der 
    Using keystore-file : /opt/tomcat/temp/keystore.ImportKey
    One certificate, no chain.
    Key and certificate stored.
    Alias:importkey  Password:importkey
    -bash-3.2$ keytool -storepasswd -new changeit -keystore keystore.ImportKey -storepass importkey
    -bash-3.2$ keytool -keypasswd -alias importkey -new changeit -keystore keystore.ImportKey -keypass importkey -storepass changeit
    -bash-3.2$ keytool -changealias -alias importkey -destalias tomcat -storepass changeit -keystore keystore.ImportKey
    -bash-3.2$ mv keystore.ImportKey idp.new.jks
    -bash-3.2$ cp idp.new.jks /opt/shibboleth-idp/credentials/
    
  1. Edit the tomcat server.xml config file to change to the new Java Key Store for the back channel query.
    -bash-3.2$ svn co svn+ssh://sxjpm@iron.alaska.edu/usr/local/iam/shib-svn/tomcat/trunk/conf
    -bash-3.2$ vi conf/server.xml
    ...
    	    <!-- added per shibb installation -->
    	    <Connector port="8443"
    	           protocol="org.apache.coyote.http11.Http11Protocol"
    	           SSLImplementation="edu.internet2.middleware.security.tomcat6.DelegateToApplicationJSSEImplementation"
    	           scheme="https"
    	           SSLEnabled="true"
    	           clientAuth="true"
    	           keystoreFile="/opt/shibboleth-idp/credentials/idp.new.jks"
    	           keystorePass="changeit" />
    ...
    :wq!
    -bash-3.2$ svn ci conf/server.xml -m "Changed back channel query to use new key/cert."
    
  1. Test config changes according to procedure. See [ Test IdP Config Change ]

References:
[ Import Key Utility ]
[ AddTrust External CA Root ]
[ InCommon Server CA ]
[ IAM Project Hosts ]
[ Test IdP Config Change ]
[ InCommon Metadata Distribution Point ]