This documentation is for WSO2 Identity Server 5.3.0 . View documentation for the latest release.

Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

Tip
titleBefore you begin

There are a few changes made to the chrome u2f extension which causes the FIDO device to not register properly as an authentication factor. Additionally, Firefox no longer supports the u2f extension anymore. Therefore, WSO2 Identity Server solves this by using the WebAuthn API to enable FIDO-based authentication. The WebAuthn API is already supported by the following browser versions:

  • Chrome(CHROME 67) 

  • Firefox (FIREFOX 60)

  • Edge (EDGE 17723)

Panel
borderColorBlack
bgColorWhite
Expand
titleClick here to view instructions for applying this fix

This fix is available for WSO2 IS 5.3.0 through the 5780 WUM update. You can apply the WUM update using the WSO2 Update Manager (WUM).

  1. Shutdown the WSO2 Identity Server if it is already running.
  2. Take a backup copy of the authenticationendpoint.war and the extracted authenticationendpoint folder found in the <CARBON_SERVER>/repository/deployment/server/webapps/ folder and then delete them.

  3. Apply the 5780 WUM update using WSO2 Update Manager.

    Warning

    To deploy a WUM update into production, you need to have a paid subscription. If you do not have a paid subscription, you can use this feature with the next version of WSO2 Identity Server when it is released. For more information on updating WSO2 Identity Server using WUM, see Getting Started with WUM in the WSO2 Administration Guide.

  4. Create the FIDO2_DEVICE_STORE table using the relevant updated DB query located in the <IS_HOME>/dbscripts/identity folder.

  5. Add the following properties to the identity.xml file found in the <IS_HOME>/repository/conf/identity folder.

    Code Block
    <FIDO>
            <WebAuthn>
                <Enable>true</Enable>
            </WebAuthn>
            <FIDO2TrustedOrigins>
                <Origin>${carbon.protocol}://${carbon.host}:${carbon.management.port}</Origin>
            </FIDO2TrustedOrigins>
    </FIDO>
    PropertyDescription
    WebAuthn.Enable

    Set this property to true to enable using the WebAuthn API. This feature is only available for the following browser versions:

    • Chrome 67 and later

    • Firefox 60 and later

    • Microsoft Edge 17723 and later

    WSO2 recommends using WebAuthn feature if you are using any of the browsers listed above.

    Note

    Note: If you have used FIDO previously, your devices must be re-enrolled once this property is set to true.

    FIDO2TrustedOrigins

    This property defines the set of origin URLs where the dashboard is hosted (e.g., https://localhost:9443).

  6. Add the following property to the identity.xml file under the <ResourceAccessControl> tag to secure the WebAuthn endpoints.

    Code Block
    <Resource context="(.*)/api/users/v2/me/webauthn(.*)" secured="true" http-method="all">
             <Permissions>/permission/admin/manage/identity</Permissions>
    </Resource>
    
    
  7. Add the following property to the identity.xml file under the <WebApp> tag of <TenantContextsToRewrite>.

    Code Block
    <Context>/api/users/v2/me/webauthn/<webauthn</Context>
  8. Add the following property to the application-authentication.xml file found in the <IS_HOME>/repository/conf/identity folder within the <AuthenticatorConfig  name="FIDOAuthenticator"> tag.

    Code Block
    <Parameter name="Fido2Auth">/authenticationendpoint/fido2-auth.jsp</Parameter>
  9. Restart the server using one of the following commands.
    1. Linux/Unix: sh wso2server.sh
    2. Windows: wso2server.bat
  10. Once you have restarted the server, navigate to the extracted authenticationendpoint folder found in the <CARBON_SERVER>/repository/deployment/server/webapps/ folder and merge any customizations to the new artifact using the backup copy of the file you took in step 2 as a reference.

...