Software token (OATH)

Scenario

The Enrollment application is used to enroll/activate a software token. Since Enrollment act as a SAML Service Provider (SP) you will decide on the SAML IdP how users should authenticate themselves. In this use case we will use Fortified ID Integrity WEB as the SAML IdP (Identity Provider). The IdP selector will provide three authenticators in this use case:

• UID and Password (Enroll) This login method/authenticator is used to login using an LDAP account to enroll for an OATH token. For username we use mail attribute on an Active Directory user. Note. Username/Password is not a secure authentication, focus here is to make it simple to get the use case to work. It is recommended to protect the Enrollment application with a strong authentication method. Feel free to add for example OTP to the use case.

• UID and OATH (Test OATH token) This authenticator is used to test your enrolled OATH token with the LDAP account. For username we use mail attribute on an Active Directory user.

• UID/PWD and OATH (Test token) This authenticator is used to test your enrolled OATH token with the LDAP account. For username we use mail attribute on an Active Directory user.

We will use Microsoft Active Directory as user store.

Prerequisite

• Server platform. Docker, Windows or Linux. In this use case we have used a Windows server with an Active Directory.

• FortifiedID Integrity Web current version

• Fortified Enrollment current version

• Microsoft SQL Server

  • Microsoft SQL Server Express

  • Microsoft SQL Server Management Studio (SSMS)

  • Create manually a database called Enrollment. If Enrollment database exist the Enrollment service will create all the tables when service start.

  • For this use case we use the sa account. Make sure the sa account has administrative rights to the database.

• LDAP directory. Location are the users to authenticate. The example code is configured to use an Active Directory. We are using mail attribute of the Active Directory user.

  • Bobby Clarke

    • Bobby Clarke (displayName)

    • bobbyc (sAMAccountName)

    • [e-mail] (mail)

    • Set a password

• OATH token app. Use Microsoft or Google Authenticator as example app.

Configuration

Download and add configuration

Remember that this use case does not describe installation of the products. Products are expected to be installed in advanced.

1. Download ZIP containing configuration for Web and Enrollment

   1. Click USE_CASE_LINK to download customer folders for Web and Enrollment.
2. Add Integrity WEB configuration to your environment.

   1. Add the customer_WEB folder to you \..\fortifiedid\web\ folder. Rename the existing customer folder to customer_ORG and rename the added one to \customer.

3. Add Enrollment configuration to your environment.

   1. Add the customer_ENROLL folder to you \..\fortifiedid\enrollment\ folder. Rename the existing customer folder to customer_ORG and rename the added one to \customer.

Update the configuration to map your environment

The downloaded folders contains all information needed. For example, a test certificate and metadata files are included and configured to work with the example applications. However, some data needs to be changed to map your environment. You need to update the LDAP information to match your environment. Since this example was done on a Windows server you might need to update file paths if you run something else. Also the http ports might need to be changed if they are not available in your environment.

To make it easy both application folders have a file called globals.json that contains the information you need to change. Config.json uses the variables in globals.json.

1. Open globals.json for \..\fortifiedid\enrollment\customer\config and \..\fortifiedid\web\customer\config folder and update:

   1. LDAP data to match your environment

   2. SQL data to match your environment

   3. File paths

   4. HTTP if needed

2. When updated, start Integrity WEB and Portal in order described below.

   1. Start SQL server. Wait until SQL server is started before moving on to start enrollment service. Verify that you have created a database called enrollment.

   2. Start Integrity WEB service. Wait until service is started before moving on. Verify server.log file that service running without errors.

   3. Start Enrollment service. If this is the first time you start the database the tables will be created in the enrollment database. Verify that you after startup is finished have a number of tables called dbo.*. Verify server.log file that service running without errors. When the service is starting, it will connect to the database and either update the tables if needed or create the tables if the do not exist. Note that you must manually have created the database.

Test the use case

There are three authenticators in this use case. See screenshot and explanation below for the three authenticators.

Enroll for an OATH token

This will use [e-mail] to log in against Active Directory to create an OATH token on a token device for Bobby.

1. Open a browser

2. Browse to https://localhost:8448/enrollment/oathsw/app You should now be redirected to https://localhost:8443/saml/authn/auth01

3. On Integrity WEB SAML IdP, click Enroll for a software token

4. In UserID, type [e-mail] and whatever password you used then click Sign in.

5. For Bobby the result should look like:
6. Click Start

7. You should see the following page:
8. On your mobile device

   1. Open your OATH app. For example Microsoft or Google Authenticator.

   2. In the app, scan the QR code. Finish adding the token.
9. Add a name for your token and a one-time password, click Activate

10. Click Close to finish the enrollment process

11. You have now successfully enrolled for an OATH token for Bobby Clarke

Test OATH token using UserID and OATH token

This step is to test that the OATH token works when authenticating. Use [e-mail] to log in against Active Directory and your OATH token.

1. Open a browser

2. Browse to https://localhost:8448/enrollment/oathsw/app You should now be redirected to https://localhost:8443/saml/authn/auth01

3. On Integrity WEB SAML IdP, click Test your token (UID/Token)

4. In Username, type [e-mail]

5. On your token device, open the OATH token app.

   1. Generate an OATH token

6. Add it to the OATH token field and click Sign in.

7. You should now be logged in to the Enrollment app again. This means it works.

Test OATH token using UserID/Password and OATH token

This step is to test that the OATH token works when authenticating. Use [e-mail] to log in against Active Directory and your OATH token.

1. Open a browser

2. Browse to https://localhost:8448/enrollment/oathsw/app You should now be redirected to https://localhost:8443/saml/authn/auth01

3. On Integrity WEB SAML IdP, click Test your token (UID/PWD + Token)

4. On the verify Username and Password page

   1. In Username, type [e-mail]

   2. In Password, type password for Bobby

   3. Click Sign in

5. On the Verify OATH token page

   1. On your token device, open the OATH token app.

      1. Generate an OATH token

   2. Add it to the OATH token field and click Sign in.

6. You should now be logged in to the Enrollment app again. This means it works.

Extra

The enrollment page consist of an image and for OATH SW a link to authenticator to download. By default Google Authenticator. Add configuration below for different behaviour to the overlay file ui_config_overrides.json. Below will link to Microsoft Authenticator and not show and images.

"enrollment_oath_sw": {
    "token_type_logo": false,
    "app_link_android": "https://apps.apple.com/us/app/microsoft-authenticator/id983156458",
    "app_link_ios": "https://play.google.com/store/apps/details?id=com.azure.authenticator&pcampaignid=web_share"
},
"enrollment_oath_hw": {
    "token_type_logo": false
},
"enrollment_passkeys": {
    "token_type_logo": false
}

Complete config.json file of Enrollment (OATH Software)

The config.json of Web can be found in the associated zip-file in this use case.

{
    "globals": "@include:globals.json",
    "modules": [
        {
            "name": "CefEventModule"
        },
        {
            "name": "HttpClient",
            "config": {
                "name": "default",
				"ssl_trust_all": true,
                "idle_timeout_ms": 5000,
                "connect_timeout_ms": 5000
            }
        },
        {
            "name": "TokensDb",
            "config": {
                "namespace": "default",
                "db_driver": "${globals.tokensdb.db_driver}",
                "encryption_key": "ABC123",
                "jdbc": {
                    "url": "${globals.tokensdb.url}",
                    "username": "${globals.tokensdb.username}",
                    "password": "${globals.tokensdb.password}"
                },
                "inactive_token_duration": "PT5M",
                "maintenance_batch_size": 100,
                "secret_key_directory": "${globals.file_paths.base_dir}/config/resources_internal/dbsecrets",
                "otp_cache_max_age_seconds": 3600,
                "oathsw": {
                    "token_issuer": "FortifiedID",
                    "active_token_duration": "P180D",
                    "totp_max_drift": 10,
                    "hotp_max_lookahead": 10,
                    "max_active_tokens": 2
                }
            }
        },
        {
            "name": "OathSwEnrollment",
            "config": {
                "namespace": "default",
                "http_port": "${globals.http.port}",
                "webroot_dir": "resources/web/oath-sw",
				"http_use_ssl": true,
                "http_keystore_ref": {
                    "type": "${globals.keystore.https.ref.type}",
                    "path": "${globals.keystore.https.ref.path}",
                    "password": "${globals.keystore.https.ref.password}"
                },
                "http_keystore_type": "${globals.keystore.https.type}",
                "http_key_alias": "${globals.keystore.https.http_key_alias}",
                "http_key_password": "${globals.keystore.https.http_key_password}",
                "http_context": "/enrollment",
                "context_path": "/oathsw",
                "http_auth_redirect_url": "/enrollment/oathsw/authn/login",
                "overlay_dirs": [
                    "${globals.file_paths.base_dir}/config/resources_external/overlays/1_oath_sw",
                    "${globals.file_paths.base_dir}/config/resources_external/overlays/0_look_and_feel"
                ],
                "token_issuer": "Fortified ID Test",
                "flow_layout": "STANDARD"
            }
        },
        {
            "name": "AuthN",
            "config": {
                "http_port": "${globals.http.port}",
                "http_use_ssl": true,
                "http_keystore_ref": {
                    "type": "${globals.keystore.https.ref.type}",
                    "path": "${globals.keystore.https.ref.path}",
                    "password": "${globals.keystore.https.ref.password}"
                },
                "http_keystore_type": "${globals.keystore.https.type}",
                "http_key_alias": "${globals.keystore.https.http_key_alias}",
                "http_key_password": "${globals.keystore.https.http_key_password}",
                "authenticators": [
                    {
                        "id": "${globals.saml.sp1.id}",
                        "type": "SAMLSP",
                        "config": {
                            "http_context": "/enrollment/oathsw/authn",
                            "context_path": "/login",
                            "success_location": "/enrollment/oathsw/login",
                            "logout_location": "/enrollment/oathsw/logged_out",
                            "metadata_output_directory": "${globals.file_paths.base_dir}/config/resources_internal/saml_sp_metadata",
                            "metadata": {
                                "url": "https://localhost:8443/saml/metadata/fortifiedid_web_saml_idp_1"
                            },
                            "entity_id": "${globals.saml.sp1.entity_id}",
                            "metadata_file_path": "${globals.saml.sp1.metadata_file_path}",
                            "sign_ref": [
                                {
                                    "keystore": {
                                        "alias": "${globals.keystore.saml.sign_ref_keystore_alias}",
                                        "key_password": "${globals.keystore.saml.sign_ref_keystore_key_password}",
                                        "password": "${globals.keystore.saml.sign_ref_keystore_password}",
                                        "path": "${globals.keystore.saml.sign_ref_keystore_path}"
                                    }
                                }
                            ]
                        }
                    }
                ]
            }
        }
    ]
}