OryFM

OryFM is an OAuth2 identity provider for FileMaker and Ory Hydra, supporting two different authentication schemes:

• basic-auth (Authentication against native FileMaker users)
• password-hash (Authentication against table based users)

FileMaker requirements

• You need FileMaker 18 or newer with the Data API enabled for your database.
• You need a couple of scripts in place, the exact kind depends on your authentication method.

Scripts for "basic-auth"

getUser

The script parameter is a JSON encoded object with the following properties:

• field, can be "id" or "username"
• value, either the ID or the username of the user

The return value of that script should be a JSON object in the following format:

{
    id : string;
    displayName : string;
    emailAddress : string;
}

Scripts for "password-hash"

getUser

The script parameter is a JSON encoded object with the following properties:

• field, can be "id" or "emailAddress"
• value, either the ID or the email address of the user

The return value of that script should be a JSON object in the following format:

{
    id : string;
    displayName : string;
    emailAddress : string;
    passwordHash : string;
}

requestPasswordResetLink

The script parameter is a JSON encoded object with the following properties:

• emailAddress, email address of the user
• uriTemplate, URI template with a {resetToken} placeholder
• debug, boolean indicating whether to return the reset URL in the response

The script should generate a reset token with an expiry date and store those in the user data. It can then generate a reset URL from the URI template and send an email to the user.

The return value of that script should be a JSON object in the following format, with the debug property only set when enabled:

{
    result : boolean;
    debug? : {
        resetLink : string;
    };
}

validatePasswordResetToken

The script parameter is a JSON encoded object with the following properties:

• resetToken, is the reset token generated by requestPasswordResetLink

The script must validate that the reset token is valid, so it must exist and not be expired. The return value of that script should be an object with a boolean indicating whether the resetToken is valid:

{
    result : boolean;
}

resetPasswordHash

The script parameter is a JSON encoded object with the following properties:

• resetToken, is the reset token generated by requestPasswordResetLink
• passwordHash, is the new password hash for the user

The script must find the user with the given reset token and update the password hash of the user. The return value of that script should be an object with a boolean indicating whether the reset was successful:

{
    result : boolean;
}

setPasswordHash

The script parameter is a JSON encoded object with the following properties:

• id, is the ID of the user
• passwordHash, is the new password hash for the user

The script must find the user with the given ID and update the password hash of the user. The return value of that script should be an object with a boolean indicating whether the update was successful:

{
    result : boolean;
}

Production installation (AWS)

Setting up the stack

For easy setup we are supplying a CloudFormation template together with OryFM, which you can find in this repository.

All parameters in the CloudFormation setup are either self-explaining or properly documented. The three important ones are these:

• OryFmDomainName: This is the primary domain name of your authentication service and the one users are generally to see.
• HydraPublicDomainName: This is the domain of the OAuth2 service your client applications communicate with.
• HydraAdminDomainName: This domain is used by your backend for token validation and to set up new clients.

The template will set up a complete stack with Hydra and OryFM running in an EC2 instance. It is also setting up HTTPS certificates with the help of CloudFront. During provisioning, you'll need to validate the certificate via ACM.

Once the machine has provisioned, it will put the generated elastic IP address in the output. You then have to create the appropriate A-records of the three selected domains pointing to that IP address. The service will become available once the certificates have been issued.

Managing clients

To manage registered clients, you need to retrieve the admin password from the AWS Secrets Manager. Once you've done that, you can use it to manage clients through the Hydra Admin API. The /clients endpoints are protected with basic authentication, with the user being admin and the generated admin password. For detailed explanation of those endpoints, please refer to:

https://www.ory.sh/docs/hydra/sdk/api#administrative-endpoints

Here's a basic example for public clients (native apps and single-page apps) using authorization code flow with PKCE:

{
    "client_id": "some-application",
    "client_name": "Some Application",
    "grant_types": [
        "authorization_code"
    ],
    "redirect_uris": [
        "https://example.com/login-callback",
        "https://example.com/silent-refresh-callback"
    ],
    "post_logout_redirect_uris": [
        "https://example.com/logout-callback"
    ],
    "response_types": [
        "code" 
    ],
    "scope": "openid email profile",
    "metadata": {
        "application_login_uri": "http://example.com",
        "first_party_client": true
    }
}

You should note that the metadata block is completely optional and just specific to OryFM. The two properties in there are:

• application_login_uri: Used by OryFM to generate links to return to the application and re-initiate the login procedure.
• first_party_client: Used by OryFM to determine whether it has to show the consent screen. First party clients do not required consent by the user.

Theming

OryFM allows to override both the CSS and all the labels.

CSS

In the CloudFormation parameters you can define the OryFmThemeCssUrl pointing to any publicly available URL. In there you can extend the Bootstrap CSS and adjust it to your needs. Changes to the CSS file will take immediate effect.

Labels

In order to customize labels within OryFM, use SSM to connect to the machine and edit the following file: /opt/oryfm/custom-labels.json. After you've completed your changes, reload oryfm by calling reload-oryfm as root.

Development

To start developing OryFM, there's handy script assisting you:

dev.sh setup

When you messed up something in a database or need a refresh, there's a command to do a reset:

dev.sh reset

Next you'll want to run the application via npm:

npm run watch

Then you can test the implementation by calling for instance this URL:

http://localhost:4444/oauth2/auth?
client_id=dev
&redirect_uri=http://localhost:12345/login-callback
&scope=openid+email+profile
&response_type=token+id_token
&state=56d21661e36c85f28159969d038d2b5f6f3ddcc7
&nonce=56d21661e36c85f28159969d038d2b5f6f3ddcc7