ASTRA

How-to: Consume ASTRA Web Service v.2 using Microsoft.NET 2.0/WSE 3.0

Introduction

This document describes how to create a Microsoft.NET client application that consumes authorization data from the ASTRA web service. The client authenticates using X509 client certificates.

Changes in this version

1. Retrieve authorizations for processes as well as persons.
   You may want to do this if you operate a service that provices access to other applications.
   Each authorization has a party attached to it. The party may be either a person or a process. The person is typically identified by a UWNetid. The process is typically identified by a UWCA-issued X.509 certificate name.

   <auth>
         <party xsi:type="Process" certName="isdev.nebula.washington.edu" certIssuerName="UW Services CA" />
     ...
   </auth>
   

2. If the party is a person who is an employee, an employee ID attribute will be returned.
   

   <auth>
     <party xsi:type="Person" regid="78EDC9806A7C11D5A4AE0004AD494FFE" uwNetid="javerage" employeeId="990006213" />
     ...
   </auth>
   

   ASTRA should not be considered the official source for mappings between Person identifiers. That source is Person Registry. Also, ASTRA synchronizes employee ID changes with the Person Directory Service, which in turn synchronizes with HEPPS, and so there may be some latency in changes.
3. Retrieve authorizations of people who can create authorizations using ASTRA (Authorizers, Delegators).
   You may want to use this if you wish to tell a user or potential user of your application whom they can contact to manage access.
   Specify an AstraRole of User, Authorizer, or Delegator; User is the default.

   <auth>
     <astraRole code="User" />
     ...
   </auth>
   

4. Perform a batch of multiple queries in a single SOAP request.
   To do a batch request, call the new GetAuthzBatch() method and specify as a parameter an array of authFilter objects.

Required software

• Microsoft .NET Framework 2.0
  (Go to http://www.microsoft.com/net and refer to the downloads link)
• Microsoft Web Services Enhancements (WSE) 3.0
  (http://msdn.microsoft.com/webservices)
• Microsoft Visual Studio .NET 2005 (optional, but used in this document)

Install software

1. Install Microsoft Web Service Enhancements (WSE) 3.0
2. Install Microsoft .NET Framework 2.0/3.0/3.5

Acquire & Install UWCA X509 client certificates

See Acquire & Install UWCA X.509 certificates

Configure ASP.NET web application to use X.509 certificates

If your application is an ASP.NET web application, see Configure ASP.NET web application to use X.509 certificates

Create .Net Project

Create c# web application named AstraWSClientDemo
Add a button to WebForm1.aspx (Button1)
Add a TextBox to WebForm1.aspx (TextBox1)
Set TextBox1.TextMode to MultiLine
Stretch TextBox1 out to a decent size.
Add a reference to Microsoft.Web.Services3.dll
Add a reference to System.Web.Services.dll

Add a web reference to https://ucs.admin.washington.edu/astraws/v2/default.asmx
The default web reference name will be edu.washington.admin.ucs, change that to AstraWS2

Add the following to the top of WebForm1.aspx.cs

using Microsoft.Web.Services3;
using System.Web.Services;
using Microsoft.Web.Services3.Security.X509;
using System.Security.Cryptography.X509Certificates;
using System.Xml;
using System.Xml.Serialization;
using System.IO;

using AstraWSClientDemo.AstraWS2;

Double click on Button1 (this will create and bring you to the click handler for Button1

void Button1_Click(object sender, EventArgs e) {
    AstraWS2.AuthzProvider proxy = new AstraWS2.AuthzProvider();

    //TODO: replace isdev.nebula.washington.edu with your certificate subject string
    X509Certificate cert = GetCert("isdev.nebula.washington.edu");
    if (cert != null) {
        proxy.ClientCertificates.Add(cert);
    }
    else {
        throw new Exception("certificate is null");
    }

    authFilter filter = new authFilter();
    filter.environment = new AstraWSClientDemo.AstraWS2.Environment();
    filter.environment.code = "eval";

    filter.astraRole = new AstraRole();
    filter.astraRole.code = "User";

    filter.privilege = new Privilege();
    filter.privilege.code = "testpriv";

    Party party = null;
    // to specify a process by cert, uncomment the following and comment out the Person code that follows
    // Process p = new Process();
    // p.certName = "isdev.nebula.washington.edu";
    // p.certIssuerName = "UW Services CA";
    // party = p;
    
    // to specify a person
    Person p = new Person();
    p.uwNetid = "astratst";
    party = p;

    filter.party = party;

    AstraWSClientDemo.AstraWS2.authz authz = proxy.GetAuthz(filter);

    XmlSerializer myXmlSerializer = new XmlSerializer(typeof(Authz));
    StringWriter myStringWriter = new StringWriter();
    myXmlSerializer.Serialize(myStringWriter, authz);

    TextBox1.Text = Server.HtmlEncode(myStringWriter.ToString());

}

Paste in the following routine:

private X509Certificate GetCert(string subject)
{
    X509Certificate cert = null;

    X509Store store = new X509Store(StoreName.My, StoreLocation.LocalMachine);

    try {
        store.Open(OpenFlags.ReadOnly);
        X509Certificate2Collection col =
               store.Certificates.Find(X509FindType.FindBySubjectName, subject, true);
        cert = col[0];
    } 
    catch (Exception e) {
        throw new Exception("Cert not found", e);
    }
    finally {
        store.Close();
    }
    return (cert);
}

Do a find on TODO: and change the values as appropriate.
Run the code, Click on the Button, and the results will be displayed in TextBox1.

Test whether person is authorized

Iterate the collection of Auth objects and check if a particular authorization exists.

	foreach(AstraWSClientDemo.AstraWS2.auth biff in authz.authCollection) {
		if (biff.privilege.code.ToLower() == "testpriv" &&
		   biff.role.code.ToLower() == "testrole" &&
		   biff.action.code.ToLower() == "testaction" &&
		   biff.spanOfControlCollection[0].type == "OrgInc" &&
		   biff.spanOfControlCollection[0].code == "014956" &&
		   biff.spanOfControlCollection[1].type == "$Lim" &&
		   biff.spanOfControlCollection[1].code == "2000") {
			Response.Write("Authorization exists!");
		} else {
			Response.Write("Authorization does not exist!");
		}
	}

The authorization returned will look something like the following:

    <auth>
      <party xsi:type="Person" regid="78EDC9806A7C11D5A4AE0004AD494FFE" uwNetid="javerage" employeeId="990006213" />
      <environment code="EVAL" />
      <astraRole code="User" />
      <privilege code="TestPriv" />
      <role code="Test_EPCatInc" codeDescription="EP Catalog Include Test" />
      <action code="TestAction" />
      <spanOfControlCollection>
        <spanOfControl type="EpCatInc" code="101" codeDescription="Correctional Industries" />
      </spanOfControlCollection>
    </auth>