ESAPIS Hash Authentication

Overview

We have incorporated a new method of client authentication into csf-security. We are calling this method "Hash Authentication", as it relies on a hashing algorithm to authenticate the client. It will be primarily used for APIs. The purpose of this authentication method is to allow client applications to authenticate to our web APIs without having to provide Touchstone credentials or manage an X509 certificate. Hash authentication was first used in the Nelnet APIs (Nelnet is an external system that exchanges data with MITSIS via an API).

How Hash Authentication Works

TBDSee here.

When Should We Use Hash Authentication?

...

• an external entity (e.g. a company outside of MIT, or an MIT academic department) and
• the API is being invoked by an applciation rather than a person using a web browser and
• X509 certificates are not suitable (this is somewhat of a judgement call)

Configuring a Web App for Hash Authentication

The code for Hash Authentication resides in CSF Security (v2.0.36-SNAPSHOT). To make use of this feature, a web application must:

1. Import a Spring hash authentication config file from CSF Security. The import should be done in the web app's Spring Security config file:

     <import resource="classpath*:applicationContext-csf-security-hash-authn.xml" />

2. Include a reference to the Hash Authentication filter in the filterChainProxy's list of filters. The filter id is "hashAuthenticationProcessingFilter" and should be the first authentication related filter in the chain - example:

     <security:filter-chain pattern="/**" filters="esapisSecurityContextNonPersistenceFilter,
              logoutFilter,
              hashAuthenticationProcessingFilter,
              esapisAuthenticationProcessingFilter,
              basicAuthenticationProcessingFilter,
              exceptionTranslationFilter,
              filterSecurityInterceptor"
     />

3. Place two properties files in the web app properties directory. These files are:

a) hash-authn-api-users.properties

This file lists the "user ids" representing clients permitted to use hash authentication along with the user's authorizations. The format of the file is a combination of Spring Security's user details property file format and our own roles/qualifiers format for specifying authorizations. The format for one user entry is:

username=password,authority[&authority],[enabled|disabled],secretKey

where authority is of the form:

role|qualifier[ qualifier]

e.g.

math.mit.edu=,ROLE_DEPTAUDIT_USER|18 8&ROLE_DEPTAUDIT_ADMIN|18,true,secret

So there are various delimiters in play:

• ‘,’ delimits the fields in the property string (highest level). Splits the property value into password, authorities, enabled flag, shared secret
• ‘&’ delimits the next level of chunks within a field. Only used in the authorities field to delimit a collection of authorities.
• ‘|’ delimits the next level. Only used in the authorities field to separate the role name from the qualifiers.
• ‘ ’ (space) delimits the next level. Only used in the qualifiers field to delimit a collection of qualifiers.

b) hash-authn-api-hash-fields.properties

This file defines the list of input fields (API parameters) that should be used in the hashing process. The key field is a API's URI and the property value field is a comma-delimited list of field names. The format for one entry is:

uri=fieldName[,fieldName]

e.g.

ESAPIS Hash Authentication

Overview

We have incorporated a new method of client authentication into csf-security. We are calling this method "Hash Authentication", as it relies on a hashing algorithm to authenticate the client. It will be primarily used for APIs. The purpose of this authentication method is to allow client applications to authenticate to our web APIs without having to provide Touchstone credentials or manage an X509 certificate. Hash authentication was first used in the Nelnet APIs (Nelnet is an external system that exchanges data with MITSIS via an API).

How Hash Authentication Works

TBD

Configuring a Web App for Hash Authentication

The code for Hash Authentication resides in CSF Security (v2.0.36-SNAPSHOT). To make use of this feature, a web application must:

1. Import a Spring hash authentication config file from CSF Security. The import should be done in the web app's Spring Security config file:

     <import resource="classpath*:applicationContext-csf-security-hash-authn.xml" />

2. Include a reference to the Hash Authentication filter in the filterChainProxy's list of filters. The filter id is "hashAuthenticationProcessingFilter" and should be the first authentication related filter in the chain - example:

     <security:filter-chain pattern="/**" filters="esapisSecurityContextNonPersistenceFilter,
              logoutFilter,
              hashAuthenticationProcessingFilter,
              esapisAuthenticationProcessingFilter,
              basicAuthenticationProcessingFilter,
              exceptionTranslationFilter,
              filterSecurityInterceptor"
     />

3. Place two properties files in the web app properties directory. These files are:

a) hash-authn-api-users.properties

This file lists the "user ids" representing clients permitted to use hash authentication along with the user's authorizations. The format of the file is a combination of Spring Security's user details property file format and our own roles/qualifiers format for specifying authorizations. The format for one user entry is:

username=password,authority[&authority],[enabled|disabled],secretKey

where authority is of the form:

role|qualifier[ qualifier]

e.g.

math.mit.edu=,ROLE_DEPTAUDIT_USER|18 8&ROLE_DEPTAUDIT_ADMIN|18,true,secret

So there are various delimiters in play:

• ‘,’ delimits the fields in the property string (highest level). Splits the property value into password, authorities, enabled flag, shared secret
• ‘&’ delimits the next level of chunks within a field. Only used in the authorities field to delimit a collection of authorities.
• ‘|’ delimits the next level. Only used in the authorities field to separate the role name from the qualifiers.
• ‘ ’ (space) delimits the next level. Only used in the qualifiers field to delimit a collection of qualifiers.

b) hash-authn-api-hash-fields.properties

This file defines the list of input fields (API parameters) that should be used in the hashing process. The key field is a API's URI and the property value field is a comma-delimited list of field names. The format for one entry is:

uri=fieldName[,fieldName]

e.g.

ESAPIS Hash Authentication

Overview

We have incorporated a new method of client authentication into csf-security. We are calling this method "Hash Authentication", as it relies on a hashing algorithm to authenticate the client. It will be primarily used for APIs. The purpose of this authentication method is to allow client applications to authenticate to our web APIs without having to provide Touchstone credentials or manage an X509 certificate. Hash authentication was first used in the Nelnet APIs (Nelnet is an external system that exchanges data with MITSIS via an API).

How Hash Authentication Works

TBD

Configuring a Web App for Hash Authentication

The code for Hash Authentication resides in CSF Security (v2.0.36-SNAPSHOT). To make use of this feature, a web application must:

...

     <security:filter-chain pattern="/**" filters="esapisSecurityContextNonPersistenceFilter,
              logoutFilter,
              hashAuthenticationProcessingFilter,
              esapisAuthenticationProcessingFilter,
              basicAuthenticationProcessingFilter,
              exceptionTranslationFilter,
              filterSecurityInterceptor"
     />

...

3. Place two properties files in the web app properties directory. These files are:
...
   role|qualifier[ qualifier]
e.g.
   math.mit.edu=,ROLE_DEPTAUDIT_USER|18 8&ROLE_OTHER_API_ADMIN,true,gr4!d
...