Network address tolerance

The SAML protocol uses the network address of the user for session tracking and message replay detection.

In many deployments however the network address of the user is not reliable because of Network Address Translation (NAT), HTTP Proxy and other network components. Use the ServiceProvider.Netmask setting in the appSettings section of web.config to adjust how the Service Provider relies on the network address.

Specify an empty value to completely disable network address validation.

Controlling resource access

Use the ASP.NET standard authorization declarations with deny and allow roles to specify access control to the resources of the web application.

In the example below, Listing 1, only authenticated users ("*") can access the resource. Anonymous unauthenticated users ("?") are will be redirected to the Ubisecure Authentication Server for authentication and presented with a login page.

<system.web>
	<authorization>
		<deny users="?"/>
		<allow users="*"/>
	</authorization>
</system.web>

Defining the User Name Attribute

By default, after authentication, the ASP.NET Context.User.Identity.Name variable contains the user principle in Distinguished Name (DN) format. In Ubisecure SSO Server version 5 or newer, this variable may optionally contain Transient or Persistent user IDs.

If the ASP.NET application requires Context.User.Identity.Name data in a different format (eg. Firstname Lastname or samAccountName from Active Directory), this can be achieved by first creating an Authorization Policy containing the desired value in another arbitrary attribute, and then mapping this attribute to Context.User.Identity.Name. Use the ServiceProvider.UsernameAttribute setting in the web.config file to specify the name of the user attribute which value will be returned by the ASP.NET Context.User.Identity.Name variable (see Listing 2).

In the example below (see Listing 2), the variable Context.User.Identity.Name will now contain the value of the attribute username, as specified in the Authorization Policy configured for this agent in Ubisecure Server Management. Figure 1 in SAML SP for ASP.NET Installation Guide contains an example Authentication Policy setting, where the username value is set to the email address of the user. The chosen configuration depends on the requirements of the target application. For more information on Authorization Policy usage, please refer to the document SSO Management.

<appSettings>
	<add key="ServiceProvider.EntityID" value="<Insert entity ID>"/>
	<add key="ServiceProvider.UsernameAttribute" value="username"/>
</appSettings> 

For more information on Authorization Policy usage, please refer to the SSO Management.

Event handlers

The Service Provider calls registered event listeners to notify the application of certain events during SAML protocol message processing.

Please refer to the API documentation for details about the following event handler interfaces (see API Documentation in SAML SP for ASP.NET application integration):

<%@ Application Language="C#" %>
<%@ Import Namespace="Ubisecure.SAML2.ServiceProvider.Event" %>
<script runat="server">
void ServiceProviderAuthentication_Login(object o, LoginEventArgs e) 
{
	// Handler for the Login Event 
}
</script>

The following example, Listing 4, will redirect the user to the specified page, for example if the cancel button is pressed during the login process.

<%@Application Language="C#"%>
<%@ Import Namespace="Ubisecure.SAML2.ServiceProvider.Event" %>
<script runat="server">
protected void ServiceProviderAuthentication_LoginError(object sender, LoginErrorEventArgs e) {
	HttpContext.Current.Response.Redirect("~/loginerror.aspx", true);
}
</script>

User attributes as specified in the Authorization Policy, are accessible from the Login event. Listing 5 is very basic example of how to access user attributes within the global.asax file.

<%@ Application Language="C#" %>
<%@ Import Namespace="Ubisecure.SAML2.ServiceProvider.Event" %>
<%@ Import Namespace="Ubisecure.SAML2.ServiceProvider.Security" %>
<script runat="server">
void ServiceProviderAuthentication_Login(object o, LoginEventArgs e) 
{
	// Handler for the Login Event 
	Response.Write("<p>Your name is " + e.Assertion.GetFirstAttributeValue("name"));
	Response.Write("<p>Your phone number is " + 
		e.Assertion.GetFirstAttributeValue("TelephoneNumber"));
	Response.End();
}
</script>

For complete technical descriptions of the API interface, please refer to the API Documentation (see API Documentation in SAML SP for ASP.NET application integration).

Membership and Role Providers

ASP.NET provides a role-based security model. SAML SP for ASP.NET can optionally be configured to provide role information according to this interface (MembershipProvider and RoleProvider). The ServiceProviderMembershipProvider and ServiceProviderRoleProvider are implementations of ASP.NET MembershipProvider and RoleProvider.

For more information on the use of roles in applications, please refer to Microsoft ASP.NET documentation.

Roles defined in an Authorization Policy in Ubilogin Management will be mapped to ASP.NET roles.

Please note that the current implementation covers only the minimum feature set required for Microsoft SharePoint integration. Any features of MembershipProvider or RoleProvider that are not supported or not implemented will raise NotImplementedException or NotSupportedException errors. For example, ServiceProviderRoleProvider.CreateRole is not supported.

To use Membership and Role Providers, the configuration in Listing 6 must be added to the web.config file within the <system.web> section.

<system.web>

<!—truncated incomplete sample -->

	<membership defaultProvider="UbiloginUsers">
		<providers>
			<clear/>
			<add name="UbiloginUsers"
				type="Ubisecure.SAML2.ServiceProvider.Security.ServiceProviderMembershipProvider,
					Ubisecure.SAML2.ServiceProvider, Version=1.13.0.0, Culture=neutral,
					PublicKeyToken=e76714ff33c956b5"/>
		</providers>
	</membership>

	<roleManager defaultProvider="UbiloginRoles" enabled="true">
		<providers>
			<clear/>
			<add name="UbiloginRoles"
				type="Ubisecure.SAML2.ServiceProvider.Security.ServiceProviderRoleProvider,
					Ubisecure.SAML2.ServiceProvider, Version=1.31.0.0, Culture=neutral,
					PublicKeyToken=e76714ff33c956b5"/>
		</providers>
	</roleManager>

<!-- truncated incomplete sample -->

</system.web>

Specifying a default role for all Authenticated users

Use the ServiceProvider.Role setting to specify the name of a ASP.NET role that is automatically associated with all users authenticated by the Service Provider. In the following example, Listing 7, all users will be assigned to a role called "UbiloginAuthenticatedUsers". This role name is arbitrary and does not need to be defined in the Authorization Policy. This role is additional to any roles received in the SAML request. This value is optional.

<appSettings>
	<add key="ServiceProvider.EntityID" value="<Insert entity ID>"/>
	<add key="ServiceProvider.Role" value="UbiloginAuthenticatedUsers"/>
</appSettings>

Access control using roles

A typical use for roles is to establish rules that allow or deny access to pages or folders. These access rules are defined in the <authorization> section of the Web.config file. The following example, Listing 8, allows users in the role of ADMIN to view pages in the folder named FolderNameToBeProtected and denies access to anyone else. Multiple roles can also be specified, e.g., <allow roles="RoleA,RoleB" />.

<configuration>
	<location path="FolderNameToBeProtected">
		<system.web>
			<authorization>
				<allow roles="ADMIN" />
				<deny users="*" />
			</authorization>
		</system.web>
	</location>
	<!-- other configuration settings here -->
<configuration>

Use the role function of Authorization Policy settings in the Ubisecure Management application to associate roles with user groups. The roles specified in Ubisecure Management are automatically mapped into ASP.NET roles. In the following example, Listing 9, unauthenticated users and users with a role of VIEWLOG are forbidden access. Other authenticated users are permitted.

<system.web>
	<authorization>
		<deny users="?"/>
		<deny roles="VIEWLOG"/>
		<allow roles="UbiloginAuthenticatedUsers"/>
	</authorization>
</system.web>

Determining role membership in ASP.NET

Use the Roles.IsUserInRole() function to test for role membership. See Listing 10.

using System.Web.Security;

if (Roles.IsUserInRole("ADMIN"))
{
	Label1.Text = User.Identity.Name + " is in admin role.";
}
else
{
	Label1.Text = User.Identity.Name + " is NOT in admin role";
} 

Listing all user roles in ASP.NET

Use the Roles.GetRolesForUser() function to list user roles. See Listing 11.

<%@ Page Language="C#" %>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">

<script runat="server">

    protected void Page_Load(object sender, EventArgs e)
    {
        string[] members = Roles.GetRolesForUser();
        foreach (string role in members)
        {
            Label1.Text += role + "<br />";
        }        
    } </script>

<html>
<head runat="server">
    <title>Role List</title>
</head>
<body>
    <p>The current user name is <%= HttpUtility.HtmlEncode(Context.User.Identity.Name) %> 
    <p>The User has the following roles:</p>
    <form id="form1" runat="server">
    <div>
        <asp:Label ID="Label1" runat="server" />
    </div>
    </form>
</body>
</html>

Requesting a specific authentication method in ASP.NET

Use the RequestedAuthnContext.AuthnContextDeclRef function to request a specific method by method ID. For example, if the calling application knows what the authentication method that the user needs to use, this selection can be made before redirect to the Ubisecure Server. See Listing 11.

protected void ServiceProviderAuthentication_AuthnRequest(object sender, AuthnRequestEventArgs e)

{
 
	e.ForceAuthn = true;
	e.RequestedAuthnContext.AuthnContextDeclRef.Add(e.IdentityProviderEntityID
+ "/saml2/names/ac/" + INSERT_METHOD_ID_HERE );
	e.Locale = "fi";

}