EPPN Service Information

Owned by Josh Helmer (Unlicensed)
Last updated: Apr 21, 2017 by Patricia Donohue
6 min read

Colleges wishing to use this service will need to contact the TechCenter so that a client Id and secret can be generated. The client Id and secret will be used to authenticate requests to this service. College will need to provide the EPPN domain when requesting credentials.

EPPN Service Information
Service NameEPPN Lookup Service
Service Version2.0

Service Description


Lookup EPPN to CCCID mappings used by the CCC Identity Provider Proxy.

SwaggerUI Docs: https://profile-eppn.ci.cccmypath.org/eppn/swagger-ui.html#/eppn-controller-v-2

Service Usage

This service is intended for colleges that would like to be able to retrieve the CCCIDs being associated with EPPNs that are routed through the CCC IDP Proxy. Every student that accesses a service through the IDP Proxy must have a CCCID. If the college IDP cannot provide the CCCID, then the IDP Proxy will attempt to map the colleges EPPN to the CCCID. This service provides a way for colleges to read those mappings so that they may potentially be imported back into the colleges SIS.

Colleges wishing to use this service will need to contact the TechCenter so that a client Id and secret can be generated. The client Id and secret will be used to authenticate requests to this service. College will need to provide the EPPN domain when requesting credentials.

A Java client library is available. The client allows property file configuration of endpoints and authentication. The Java client library will handle lookup up the OpenId token, setting the Authorization header, hitting the REST endpoint and converting data into Java objects. To import the library include the following segment in your pom file:

<properties>
    <!-- todo:  need to create a release version -->
    <ccc.common-identity.version>1.1.0-SNAPSHOT</ccc.common-identity.version>
	<eppn-service.version>1.1-SNAPSHOT</eppn-service>
</properties>


<repositories>
    <repository>
        <id>nexus-releases</id>
        <name>CCC Nexus Repo - Release</name>
        <url>https://nexus.dev.ccctechcenter.org/content/repositories/releases</url>
        <releases>
            <enabled>true</enabled>
        </releases>
        <snapshots>
            <enabled>false</enabled>
        </snapshots>
    </repository>
    <repository>
        <id>nexus-snapshots</id>
        <name>CCC Nexus Repo - Snapshots</name>
        <url>https://nexus.dev.ccctechcenter.org/content/repositories/snapshots</url>
        <releases>
            <enabled>false</enabled>
        </releases>
        <snapshots>
            <enabled>true</enabled>
        </snapshots>
    </repository>
</repositories>

<dependencies>
    <dependency>
        <groupId>net.cccnext.services</groupId>
        <artifactId>eppn-service-client</artifactId>
        <version>${eppn-service.version}</version>
    </dependency>
    <dependency>
        <groupId>net.cccnext</groupId>
        <artifactId>common-identity</artifactId>
        <version>${ccc.common-identity.version}</version>
    </dependency>
</dependencies>


To configure the EPPN Service for a spring boot application:

@Configuration
@PropertySources({
        @PropertySource("classpath:defaults.properties"),
        @PropertySource(value = "file:overrides.properties", ignoreResourceNotFound = true),
})
@EnableConfigurationProperties
public class Config {
    @Autowired
    EppnServerSettings serverSettings;

    /**
     * Configure the EPPN service object.  EPPN service object provides the following methods:
     *
     * Eppn getEppnMapping(String eppn);
     * Page<Eppn> getNewMappings();
     * Page<Eppn> getNewMappings(int page, int pageSize);
     * Page<Eppn> getMappingsSince(Date d);
     *
     * List<BatchStatus<String>> markAsDownloaded(String... eppn);
     * List<BatchStatus<String>> markAsDownloaded(List<Eppn> eppnList);
     */
    @Bean
    public IEppnService getEppnService() throws NoSuchAlgorithmException, KeyStoreException, KeyManagementException {
        EppnV2Service svc = new EppnV2Service();
        svc.setRestOperations(getRestTemplate());
        svc.setServerSettings(serverSettings);

        return svc;
    }


    @Bean
    public RestOperations getRestTemplate() throws KeyStoreException, NoSuchAlgorithmException, KeyManagementException {
        ServiceAccountManager manager = getServiceAccountManager();
        CCCRestTemplate template = new CCCRestTemplate();
        template.setJwtGetter(manager);

        return template;
    }


    @Bean
    public ServiceAccountManager getServiceAccountManager() {
        return new ServiceAccountManager(serverSettings.getBaseTokenUrl(), serverSettings.getClientId(), serverSettings.getClientSecret());
    }


    @Bean
    public static PropertySourcesPlaceholderConfigurer propertyConfig() {
        return new PropertySourcesPlaceholderConfigurer();
    }
}


Config file:

eppn-service.server=profile-eppn.cccmypath.org
eppn-service.contextPath=/eppn
eppn-service.secure=true
eppn-service.allowInsecureHttps=false

eppn-service.baseTokenUrl=https://login.cccmypath.org/f
eppn-service.clientId=NEEDS_OVERRIDE
eppn-service.clientSecret=NEEDS_OVERRIDE




Release Notes
Valid Period4/26/2017 -
Service Location

CI: https://profile-eppn.ci.cccmypath.org/eppn/*

TEST: https://profile-eppn.test.cccmypath.org/eppn/*

PILOT: https://profile-eppn.pilot.cccmypath.org/eppn/*

PROD: https://profile-eppn.cccmypath.org/eppn/*

Methods

Get EPPN – lookup a single EPPN → CCCID mapping

Mappings Created Since – find all EPPN → CCCID mappings created since a specific date

Get New Mappings – find all EPPN → CCCID mappings that have not previously been marked as downloaded

Mark Mapping as Downloaded – Mark an EPPN → CCCID mapping as downloaded


Service Operation: Get EPPN
Name/eppn/2.0/eppn-mappings/{EPPN}
DescriptionLookup the mapping for a single EPPN
HTTP MethodGET
Preconditions

Caller must have have a valid OpenID token

Caller clientId must match the domain of the requested EPPN. (ie. If the eppn is jdoe@santarosa.edu, the clientId for the caller must be "santarosa.edu")

Post-conditions
Message Exchange Pattern

Request is received

EPPN mapping is looked up

Mapping is returned

Input

Parameters
EPPNDescriptionThe College EPPN to lookup
TypePath Parameter
RequiredYes
DefaultN/A
Output
DescriptionEPPN Mapping JSON
Data Type
{
  "authSource": "string",
  "cccId": "string",
  "createTime": "2017-03-24T22:47:08.089Z",
  "downloaded": boolean,
  "eppn": "string"
}
Faults
Faults
UnauthorizedDescriptionCalling service has not been authenticated
Http Status Code401
Additional Information
ForbiddenDescriptionCalling service has been authenticated, but does not have permissions to make this request
HTTP Status Code403
Additional Information


Service Operation: Get Mappings Created Since
Name/eppn/2.0/eppn-mappings/since/{DATE}
Description

Lookup all mappings that have an authsource matching the clientId of the caller that have been entered since DATE.

HTTP MethodGET
Preconditions

Caller must have have a valid OpenID token

DATE Must be in YYYY-MM-DD format

Post-conditions
Message Exchange Pattern

Request is received

EPPN mappings are looked up

List of mappings is returned

Input

Parameters
DATEDescriptionLookup all EPPN mappings for the given college since DATE (inclusive). Date must be in YYYY-MM-DD format.
TypePath Parameter
RequiredYes
DefaultN/A
pageSizeDescriptionMaximum number of mappings to return per request
TypeQuery Parameter
RequiredNo
Default1000
pageNumberDescription0 based index of the page of records to retrieve
TypeQuery Parameter
RequiredNo
Default0
Output
DescriptionA page of EPPN mappings
Data Type
{
  "data": [
    {
      "authSource": "string",
      "cccId": "string",
      "createTime": "2017-03-24T22:58:08.904Z",
      "downloaded": boolean,
      "eppn": "string"
    }
  ],
  "pageNumber": integer,
  "pageSize": integer,
  "totalElements": integer
}
Faults
Faults
UnauthorizedDescriptionCalling service has not been authenticated
Http Status Code401
Additional Information
ForbiddenDescriptionCalling service has been authenticated, but does not have permissions to make this request
HTTP Status Code403
Additional Information

Service Operation: Get New Mappings
Name/eppn/2.0/eppn-mappings/new-mappings
Description

Lookup all mappings that have an authsource matching the clientId of the caller that have not previously been marked as downloaded (See: Service Operation: Mark downloaded)

HTTP MethodGET
Preconditions

Caller must have have a valid OpenID token

Post-conditions
Message Exchange Pattern

Request is received

EPPN mappings are looked up

List of mappings is returned

Input

Parameters
pageSizeDescriptionMaximum number of mappings to return per request
TypeQuery Parameter
RequiredNo
Default1000
pageNumberDescription0 based index of the page of records to retrieve
TypeQuery Parameter
RequiredNo
Default0

Output

DescriptionA page of EPPN mappings
Data Type
{
  "data": [
    {
      "authSource": "string",
      "cccId": "string",
      "createTime": "2017-03-24T22:58:08.904Z",
      "downloaded": boolean,
      "eppn": "string"
    }
  ],
  "pageNumber": integer,
  "pageSize": integer,
  "totalElements": integer
}
Faults
Faults
UnauthorizedDescriptionCalling service has not been authenticated
Http Status Code401
Additional Information
ForbiddenDescriptionCalling service has been authenticated, but does not have permissions to make this request
HTTP Status Code403
Additional Information

Service Operation: Mark Downloaded
Name/eppn/2.0/eppn-mappings/batch/downloaded
Description

Mark a set of EPPN mappings as downloaded. This operation affects the data returned from the /eppn/eppn-mappings/new-mappings request.

HTTP MethodPOST
Preconditions

Caller must have have a valid OpenID token

Post-conditions
Message Exchange Pattern

Request is received

EPPN mappings are looked up

List of mappings is returned

Input

Parameters
eppnValsDescriptionAn array of EPPN mappings to mark as having been downloaded.
TypeBody Content
RequiredYes
DefaultN/A
Example["jdoe1@santarosa.edu", "jdoe2@santarosa.com"]
Output
DescriptionAn array of status objects. The array will consist of a single record for each EPPN listed in the request. The "status" field be set to either "Updated" or "Error"
Data Type
[
  {
    "entityId": "string" // eppn value
    "status": "string"   // will be either "Updated" or "Error"
  }
]
Faults
Faults
UnauthorizedDescriptionCalling service has not been authenticated
Http Status Code401
Additional Information
ForbiddenDescriptionCalling service has been authenticated, but does not have permissions to make this request
HTTP Status Code403
Additional Information