How To
ForgeRock Identity Platform
Does not apply to Identity Cloud

How do I export and import SAML2 metadata in AM (All versions)?

Last updated Jun 21, 2021

The purpose of this article is to provide information on exporting and importing SAML2 metadata in AM. SAML metadata is split between standard and extended metadata files in XML format. These files contain information about the IdP or SP entity provider and are required when configuring federation or sharing metadata with other entity providers. This information does not apply to WS-Federation entities.


2 readers recommend this article

Overview

Exporting your metadata allows you to share metadata with other entity providers, create backups and can also be useful for troubleshooting your configuration. Importing metadata allows you to create remote entity providers. 

Note

You cannot import non-standard SAML2 metadata files (such as ADFS or Microsoft Online) without making manual changes first. Additionally, you cannot import metadata files relating to WS-Federation entities.

The following options are available for importing and exporting metadata:

Note

If your metadata is signed, you must ensure AM trusts the signing certificate by importing it into the AM keystore. If AM does not trust this certificate, metadata imports will fail. See FAQ: SAML certificate management in AM 5.x and 6.x (Q. Do I have to import a certificate into the keystore for XML signing or will AM use the certificate provided in the metadata?) for further information.

Using Amster (export and import)

Amster commands can be used to export and import SAML metadata for IdP and SP entity providers.

If you want to create new entity providers, see How do I create a SAML2 IdP or SP entity provider in AM (All versions) using REST or Amster? for further information.

Export

Use the following command to export: 

am> export-config --path /path/to/export --realm / --realmEntities 'Saml2Entity'

Metadata for each entity provider will be written to a separate JSON file in the Saml2Entity directory within /path/to/export/realms/[realmName].

Import

Use the following command to import: 

am> import-config --path /path/to/export

Using ssoadm (export and import)

ssoadm commands can be used to export and import SAML metadata for IdP and SP entity providers. If you want to create new entity providers, see How do I create a hosted IdP or SP in AM (All versions) using ssoadm? and How do I register a remote IdP or SP in AM (All versions) using ssoadm? for further information.

You can export or import standard metadata files, extended metadata files or both. These example commands export and import both metadata files; you can drop either the -m or -x option if you only require one file.

Export

Use the following command for exporting metadata:

$ ./ssoadm export-entity -u [adminID] -f [passwordfile] -e [realmname] -y [entityID] -c saml2 -m [metadataXMLfile] -x [extendedXMLfile]

replacing [adminID], [passwordfile], [realmname], [entityID], [metadataXMLfile] and [extendedXMLfile] with appropriate values.

Import

Use the following command for importing metadata:

$ ./ssoadm import-entity -u [adminID] -f [passwordfile] -e [realmname] -t [entityCOT] -c saml2 -m [metadataXMLfile] -x [extendedXMLfile]

replacing [adminID], [passwordfile], [realmname], [entityCOT], [metadataXMLfile] and [extendedXMLfile] with appropriate values.

Using your browser or curl (export only)

You can access standard metadata by navigating to the metadata URL in your browser or by exporting it to a file using a curl command such as:

$ curl --output metadata.xml "[URL]"

The URL for metadata is in the following format:

[ServerURL]/saml2/jsp/exportmetadata.jsp?entityid=[entityID]&realm=/realmname

Where:

  • [ServerURL] is the full AM server URL, for example, http://host1.example.com:8080/openam
  • [entityID] is the name of your entity provider (IdP or SP), for example, EmployeesSP.
  • realmname is the name of the realm in which the entity provider is configured, for example, /employees. If the entity is configured in the top level realm (/), you can exclude the &realm parameter.

For example, with the above details: 

  • The URL to access your metadata is: http://host1.example.com:8080/openam/saml2/jsp/exportmetadata.jsp?entityid=EmployeesSP&realm=/employees
  • The curl command to export your metadata to file is:$ curl --output metadata.xml "http://host1.example.com:8080/openam/saml2/jsp/exportmetadata.jsp?entityid=EmployeesSP&realm=/employees"

Import

Although there is not an equivalent import option, you can effectively import metadata by performing a HTTP PUT to the /json/realm-config/federation/entityproviders/saml2/{id}#_update endpoint. You can try this out using the API Explorer.

You must pass the updated metadata and entityConfig XML documents in the body/payload of the request and ensure characters in the XML documents are escaped correctly. In particular, you must escape double quotes (") with a single backslash, for example \" See How do I create a SAML2 IdP or SP entity provider in AM (All versions) using REST or Amster? for examples of the required format.

Using the console (import only)

You can import SAML metadata via the console in order to create a new remote entity provider.

AM 7 and later

  • You can only import standard metadata for remote entity providers. Navigate to Realms > [Realm Name] > Applications > Federation > Entity Providers, click Add Entity Provider, select Remote and upload the metadata.
  • Extended metadata cannot be imported through the AM console as it is not required when creating an entity provider nor is it shared.

Pre-AM 7

There are two methods available:

  • Import entity:
    • AM 6.x console: navigate to Realms > [Realm Name] > Applications > Federation > Entity Providers and click Import Entity. This allows you to import the standard metadata and optionally the extended metadata. You must import the extended metadata at the same time if it is required; it cannot be done later.
    • AM 5.x console: navigate to: Realms > [Realm Name] > Applications > SAML > Circle of Trust Configuration > Entity Providers and click Import Entity. This allows you to import the standard metadata and optionally the extended metadata. You must import the extended metadata at the same time if it is required; it cannot be done later.
  • Common Tasks: navigate to: Realms > [Realm Name] > Common Tasks > Configure SAMLv2 Provider > Create Hosted ... Provider task. When you use these tasks to create an entity provider, you have the option of providing metadata as part of the creation process.
Note

You cannot access these options in the admin console if you are using AM 6.5 with Java 11. See Federation related pages do not display in the console with a java.lang.NoClassDefFoundError: sun/misc/CharacterEncoder error in AM 6.5.x for further information.

See Also

How do I change the metaAlias for an existing IdP or SP in AM (All versions)?

FAQ: SAML federation in AM

SAML Federation in AM

SAML v2.0 Guide

Amster User Guide

Related Training

N/A

Related Issue Tracker IDs

N/A


Copyright and Trademarks Copyright © 2021 ForgeRock, all rights reserved.